Migrate to the new version

What's new?

The recent update of P4-Utils introduced several improvements, affecting also P4-Learning. Indeed P4-Utils is the framework that makes it possible to create virtual networks with P4 devices in them. Hereafter, we list the most important features that were added or modified.

• The application is now fully based on Python 3.
• The legacy JSON configuration file used to start the network has been simplified.
• The network can now be started also using a Python script and the new NetworkAPI.
• P4Runtime is currently available with a new API.
• The legacy Thrift API and client have been kept for compytibility reasons.

Notice
P4Runtime is only partially available because of some bugs in the implementation of PI, the gRPC server used by the software switches provided by BMv2. In particular, consider that registers currently cannot be read or written using the P4Runtime API.

All the exercises and examples have been already migrated to the new version and they are now compatible with the new framework. However, should you have customized examples crafted from the old ones, please make sure that you have ported any controller to Python 3 and that the JSON network configuration file is compliant with the new specification.

For further information about the new P4-Utils, check out the online documentation.

How to migrate to the new version?

JSON Network Configuration

Consider that obj is the main object contained in the JSON network configuration file (i.e. the p4app.json file contained in the folders of the exercises and examples). Then we have the following major changes between the old and the new JSON network configuration file. Please remember that, because of these changes, old JSON configuration files are not compatible with the new version of P4-Utils.

Old version	New version	Description	Default behaviour	JSON Data Type
obj["program"]	obj["p4_src"]	Path to the default program for all the P4 switches.	If not specified, then switches are initialized with empty P4 source.	string
obj["switch"]	removed	Default switch binary to use. Now the switch binary configuration relies on the Python Switch class passed to P4-Utils.		string
obj["compiler"]	removed	Default compiler binary to use. Now the compiler binary configuration relies on the Python compiler class passed to P4-Utils. By default, now class P4C (a Python wrapper around P4C) is used as compiler.		string
obj["options"]	obj["compiler_module"]["options"]	Options to pass to the compiler.		string
obj["switch_cli"]	removed	Default Thrift client binary to configure the switches.		string
not present	obj["tasks_file"]	Path to the file that contains all the tasks to execute in the nodes.	If not specified, no task file is considered.	string
obj["topo_module"]	removed	Default Mininet Topo class to use. Now this setting cannot be specified anymore because we always use the default one.		object
obj["controller_module"]	removed	Default controller class to use to configure all the switches.		object
obj["topodb_module"]	removed	Default topology database class to query network information and save it to the disk. Now this setting cannot be specified anymore because we always use the default one.		object
not present	obj["host_node"]	Default Mininet host class to use.	If not specified, the default Mininet class will be used.	object
not present	obj["switch_node"]	Default Mininet switch class to use.	If not specified, the default P4Switch class will be used.	object
not present	obj["router_node"]	Default Mininet router class to use.	If not specified, the default FRRouter class will be used.	object
not present	obj["compiler_module"]	Default P4 compiler class to use.	If not specified, the default P4C class will be used.	object
not present	obj["client_module"]	Default Thrift client class to use to configure the switches.	If not specified, the default ThriftClient class will be used.	object
obj["topology"]["default_delay"]	obj["topology"]["default"]["delay"]	Links default transmission delay (ms).	If not specified, no delay is set.	number
obj["topology"]["default_bw"]	obj["topology"]["default"]["bw"]	Links default bandwidth (Mbps).	If not specified, no bandwidth limit is set.	number
obj["topology"]["default_loss"]	obj["topology"]["default"]["loss"]	Links default loss.	If not specified, no loss will be set.	number
obj["topology"]["default_link_weight"]	obj["topology"]["default"]["weight"]	Links default weight.	If not specified, link weight is set to 1.	number
obj["topology"]["default_queue_length"]	obj["topology"]["default"]["max_queue_size"]	Links default maximum queue length.	If not specified, no maximum queue size will be set.	number
obj["topology"]["auto_gw_arp"]	obj["topology"]["default"]["auto_gw_arp"]	Populate the ARP table of hosts with the default gateway MAC address. This prevents the exchange of ARP requests among hosts and default gateway.	If not specified, it is set to true.	boolean
obj["topology"]["auto_arp_tables"]	obj["topology"]["default"]["auto_arp_tables"]	Populate the ARP table of hosts with the MAC addresses of all the hosts in the same subnet. This prevents the exchange of ARP requests among hosts.	If not specified, it is set to true.	boolean
obj["topology"]["switches"][<switch_name>]["program"]	obj["topology"]["switches"][<switch_name>]["p4_src"]	Switch-specific P4 source.	If not specified, the source from obj["p4_src"] will be used.	string

More information about JSON network configuration file is provided in the official P4-Utils documentation. Check it out!

Python Network Configuration

Beside having the JSON network configuration method, one can start and initialize the network using also the new Python NetworkAPI. Hereafter, we provide a simple example of how to use this new method and a comparison with the legacy JSON configuration file. If you need more information and instructions on how to exploit this functionality, please check out the P4-Utils documentation.

from p4utils.mininetlib.network_API import NetworkAPI

net = NetworkAPI()

# Network general options
net.setLogLevel('info')
net.enableCli()

# Network definition
net.addP4Switch('s1')
net.setP4CliInput('s1', 's1-commands.txt')
net.addP4Switch('s2')
net.setP4CliInput('s2', 's2-commands.txt')
net.addP4Switch('s3')
net.setP4CliInput('s3', 's3-commands.txt')
net.setP4SourceAll('program.p4')

net.addHost('h1')
net.addHost('h2')
net.addHost('h3')
net.addHost('h4')

net.addLink('h1', 's1', weight=5)
net.setBw('h1', 's1', 20)
net.setDelay('h1', 's1', 20)
net.setMaxQueueSize('h1', 's1', 100)
net.setLoss('h1', 's1', 0.01)
net.addLink('h2', 's2')
net.addLink('s1', 's2')
net.addLink('h3', 's3')
net.addLink('h4', 's3')
net.addLink('s1', 's3')

# Assignment strategy
net.mixed()

# Nodes general options
net.enablePcapDumpAll()
net.enableLogAll()

# Start the network
net.startNetwork()

The Python script shown above is equivalent to the following JSON network configuration file. Indeed, both snippets define the same network topology. You can read more about the JSON network configuration file in the P4-Utils documentation.

{
  "p4_src": "program.p4",
  "cli": true,
  "pcap_dump": true,
  "enable_log": true,
  "topology": {
    "assignment_strategy": "mixed",
    "links": [
      ["h1", "s1", {"delay":"20ms", "loss": 1, "bw": 20, "max_queue_size": 100, "weight":5}],
      ["h2", "s2"],
      ["s1", "s2"],
      ["h3", "s3"],
      ["h4", "s3"],
      ["s1", "s3"]
    ],
    "hosts": {
      "h1": {
      },
      "h2": {
      },
      "h3": {
      },
      "h4": {
      }
    },
    "switches": {
      "s1": {
        "cli_input": "s1-commands.txt"
      },
      "s2": {
        "cli_input": "s2-commands.txt"
      },
      "s3": {
        "cli_input": "s3-commands.txt"
      }
    }
  }
}