p4utils.p4run module

This module is responsible for the legacy network configuration method that makes use of JSON files. Indeed, it uses the information contained within it to start and configure all the components of the virtualized network.

class p4utils.p4run.AppRunner(conf_file, cli_enabled=True, log_dir=None, pcap_dir=None, verbosity='info')[source]

Bases: p4utils.mininetlib.network_API.NetworkAPI

Class used to run P4 applications from a JSON configuration file.

The AppRunner creates a Mininet network reading information from the JSON configuration file. It also specifies whether logs and sniffed packets are to be saved on the disk at some location.

Parameters:
  • conf_file (str) – a JSON file which describes the Mininet topology
  • cli_enabled (bool) – enable Mininet CLI
  • log_dir (str) – directory for Mininet log files
  • pcap_dir (str) – directory where to store pcap files
  • verbosity (str) – amount of information shown during the execution

Possible verbosity values, listed from the most to less verbose, are the following:

  • debug
  • info
  • output
  • warning
  • warn
  • error
  • critical

Example

The structure of the JSON network configuration file parsed by the AppRunner is the following:

{
    "p4_src": <path to gobal p4 source> (string),
    "cli": <true|false> (bool),
    "pcap_dump": <true|false> (bool),
    "enable_log": <true|false> (bool),
    "tasks_file": <path to the tasks file> (string),
    "host_node":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string)
    },
    "switch_node":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string)
    },
    "router_node":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string)
    },
    "compiler_module":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string),
        "options": <options passed to init> (dict)
    },
    "client_module":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string),
        "options": <options passed to init> (dict)
    },
    "mininet_module":
    {
        "file_path": <path to module> (string),
        "module_name": <module file name> (string),
        "object_name": <module object name> (string)
    },
    "exec_scripts":
    [
        {
            "cmd": <path to script> (string),
            "reboot_run": <true|false> (bool)
        },
        ...
    ],
    "topology":
    {
        "assignment_strategy": <assignment strategy> (string),
        "default":
        {
            <default links and hosts configurations, see parse_links>
        },
        "links":
        [
            <see parse_links>
        ],
        "hosts":
        {
            <see parse_hosts>
        },
        "switches":
        {
            <see parse_switch>
        },
        "routers":
        {
            <see parse_routers>
        }
    }
}

Inside the network configuration file, several modules and nodes JSON objects can be present. These are the possible values:

  • host_node loads an extension to Mininet node class into the homonymous attribute.
  • switch_node loads an extension to Mininet switch node class into the homonymous attribute.
  • router_node loads an extension to Mininet node class into the homonymous attribute.
  • mininet_module loads an extension to Mininet network class.
  • compiler_module loads the external P4 compiler class.
  • client_module loads the external Thrift client class.

Note

None of the modules or nodes are mandatory. In case they are not specified, default settings will be used. For further information about how these modules are imported and the related JSON syntax, please check out this helper function.

cli_enabled[source]

enable an extension to Mininet CLI after the network starts.

Type:bool
log_enabled[source]

enable saving log files to the disk.

Type:bool
log_dir[source]

directory used to store log files.

Type:str
pcap_dump[source]

generate .pcap files for interfaces.

Type:bool
pcap_dir[source]

directory where to store .pcap files.

Type:str
hosts[source]

dictionary of host and their properties.

Type:dict
switches[source]

dictionary of switches and their properties.

Type:dict
routers[source]

dictionary of routers and their properties.

Type:dict

dictionary of mininet links and their properties.

Type:dict
clients[source]

list of Thrift clients (one per P4 switch) to populate tables.

Type:list
compilers[source]

list of compiler instances (one per P4 source provided) to compile P4 code.

Type:list
conf[source]

parsed configuration from the JSON configuration file.

Type:dict
net[source]

network instance implemented using an extension to Mininet network class.

Type:mininet.net.Mininet
host_node[source]

extension to Mininet node class used as default host class.

Type:type
switch_node[source]

extension to Mininet switch node class used as default switch class.

Type:type
router_node[source]

extension to Mininet node class used as default router class.

Type:type
execute_scripts()[source]

Executes the script listed in the JSON network configuration file.

parse_hosts(unparsed_hosts)[source]

Parses hosts from the JSON configuration files and add them to the network initializer.

Parameters:unparsed_host (dict) – dictionary of hosts and properties retrieved from the JSON network configuration file

Example

Hosts have the following description in the topology field of the JSON network configuration file:

"hosts":
{
    host_name:
    {
        "scheduler": <true|false> (bool) (*),
        "socket_path": <dir to socket file> (string) (*),
        "defaultRoute": "via <gateway ip>" (string) (*),
        "dhcp": <true|false> (bool) (*),
        "log_enabled" : <true|false> (bool) (*),
        "log_dir": <log path for host> (string) (*),
        "host_node": <custom host node> (dict) (*)
    },
    ...
}

Note

None of the fields marked with (*) is mandatory. If they are not specified default values will be used.

Load a list of links descriptions of the form.

Parameters:uparsed_links (list) – list of links and properties retrieved from the JSON network configuration file

Example

Links have the following description in the topology field of the JSON network configuration file:

"links":
[
    [
        node1,
        node2,
        {
            "weight": <link weight> (int) (*),
            "port1": <number of port1> (int) (*),
            "port2": <number of port2> (int) (*),
            "intfName1": <name of the interface1> (string) (*),
            "intfName2": <name of the interface2> (string) (*),
            "addr1": <mac address of interface1> (string) (*),
            "addr2": <mac address of interface2> (string) (*),
            "params1": <parameters for interface1> (dict) (*),
            "params2": <parameters for interface2> (dict) (*),
            "bw": <bandwidth weight> (int) (*),
            "delay": <transmit delay> (int) (*),
            "loss": <link data loss> (float) (*),
            "max_queue_size": <max queue size> (int) (*)
        }
    ],
    ...
]

One can also specify default values for some links and hosts configuration parameters. In particular, this can be done by putting the following structure in the topology field of the JSON network configuration file:

"default":
{
    "weight": <weight> (int) (*),
    "bw": <bandwidth> (int) (*),
    "delay": <transmit_delay> (int) (*),
    "loss": <loss> (float) (*),
    "max_queue_size": <max_queue_size> (int) (*),
    "auto_arp_tables": <true|false> (bool) (*),
    "auto_gw_arp": <true|false> (bool) (*)
}

Note

None of the fields marked with (*) is mandatory. If they are not specified default values will be used.

parse_routers(unparsed_routers)[source]

Parse hosts and add them to the network. Hosts have the following structure:

Parameters:unparsed_routers (dict) – dictionary of routers and properties retrieved from the JSON network configuration file

Example

Routers have the following description in the topology field of the JSON network configuration file:

"routers":
{
    router_name:
    {
        "int_conf": <path to the router's integrate configuration file> (string),
        "conf_dir": <path to the directory which contains the folder
                    (named after the router) with the configuration
                    files for all the daemons> (string),
        "router_node": <custom router node> (dict) (*),
        "zebra": <true|false> (bool) (*),
        "bgpd": <true|false> (bool) (*),
        "ospfd": <true|false> (bool) (*),
        "ospf6d": <true|false> (bool) (*),
        "ripd": <true|false> (bool) (*),
        "ripngd": <true|false> (bool) (*),
        "isisd": <true|false> (bool) (*),
        "pimd": <true|false> (bool) (*),
        "ldpd": <true|false> (bool) (*),
        "nhrpd": <true|false> (bool) (*),
        "eigrpd": <true|false> (bool) (*),
        "babeld": <true|false> (bool) (*),
        "sharpd": <true|false> (bool) (*),
        "staticd": <true|false> (bool) (*),
        "pbrd": <true|false> (bool) (*),
        "bfdd": <true|false> (bool) (*),
        "fabricd" : <true|false> (bool) (*)
    },
    ...
}

Note

None of the fields marked with (*) is mandatory. If they are not specified default values will be used. Moreover, if int_conf is specified, then conf_dir is ignored.

parse_switches(unparsed_switches)[source]

Parses the switches and adds them to the network.

Parameters:unparsed_switches (dict) – dictionary of switches and properties retrieved from the JSON network configuration file

Example

Switches have the following description in the topology field of the JSON network configuration file:

"switches":
{
    switch_name:
    {
        "p4_src": <path to p4 program> (string) (*),
        "cpu_port": <true|false> (bool) (*),
        "cli_input": <path to cli input file> (string) (*),
        "switch_node": <custom switch node> (dict) (*),
        "log_enabled" : <true|false> (bool) (*),
        "log_dir": <log path for switch binary> (string) (*),
        "pcap_dump": <true|false> (bool) (*),
        "pcap_dir": <path for pcap files> (string) (*),
        "sw_bin": <switch binary> (string) (*),
        "thrift_port": <thrift port> (int) (*),
        "grpc_port": <grpc port> (int) (*)
        "priority_queues_num": <queues num> (int) (*)
    },
    ...
}

Note

None of the fields marked with (*) is mandatory. If they are not specified default values will be used.

p4utils.p4run.get_args()[source]

Parses command line options.

Returns:namespace containing all the argument parsed.
Return type:argparse.Namespace

Here is a complete list of the command line invocation options available with p4run:

  • --config is the path to configuration (if it is not specified, it is assumed to be ./p4app.json).
  • --log-dir is the path to log files (if it is not specified, it is assumed to be ./log).
  • --pcap-dir is the path to the .pcap files generated for each switch interface (if it is not specified, it is assumed to be ./pcap).
  • --verbosity specifies the desired verbosity of the output (if it is not specified, it is assumed to be set to info). Valid verbosity values are listed here.
  • --no-cli disables the Mininet client (it is enabled by default).
  • --clean cleans old log files, if specified.
  • --clean-dir cleans old log files and closes, if specified.
p4utils.p4run.main()[source]

Cleans up files created by old executions and starts the virtual network.