p4utils.mininetlib.network_API module

This module provides an API to easily and programmatically build a virtual network using Mininet as framework. It is an extension of mininet.topo. Here, you will find the documentation for all the methods that will help you instantiate and start the network.

class p4utils.mininetlib.network_API.NetworkAPI(*args, **params)

Bases: mininet.topo.Topo

Network definition and initialization API.

cli_enabled

enable an extension to Mininet CLI after the network starts.

Type:bool

hosts

dictionary of host and their properties.

Type:dict

sw_clients

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

Type:list

compilers

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

Type:list

net

network instance implemented using an extension to Mininet network class.

Type:mininet.net.Mininet

modules

dictionary of external modules used by the API.

Type:dict

ipv4_net

IPv4 network address generator (by default within the network 10.0.0.0/8). a different network can be specified using setIpBase().

Type:ipaddress.IPv4Network

topoFile

path to the JSON topology database file.

Type:str

cpu_bridge

name of the bridge used to connect all the CPU ports of the P4 switches.

Type:str

auto_gw_arp

automatically set gateways’ MAC in the ARP tables of each host.

Type:bool

auto_arp_tables

automatically populate the ARP tables of each hosts with MACs from the other hosts present in the same subnetwork.

Type:bool

scripts

list of script to execute in the main namespace.

Type:list

tasks

dictionary containing scheduled tasks.

Type:dict

addHost(name, **opts)

Adds P4 host node to the network.

Parameters:

• name (str) – host name
• **opts – host options (optional)

Returns:

host name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addLink(node1, node2, port1=None, port2=None, key=None, **opts)

Adds link between two nodes.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• port1 (int) – port number on the first node (optional)
• port2 (int) – port number on the second node (optional)
• key (int) – id used to identify multiple edges which link two same nodes (optional)
• **opts – link options as listed below (optional)

In particular, **opts can include the following:

• intfName1 (str): name of the interface of the first node
• intfName2 (str): name of the interface of the second node
• addr1 (str) : MAC address of the interface of the first node
• addr2 (str) : MAC address of the interface of the second node
• weight (int) : weight used to compute shortest paths

Returns:key of the link between node1 and node2. Return type:int

Note

If key is None, then the next available number is used. If not specified, all the optional fields are assigned automatically by the method auto_assignment() before the network is started.

Warning

The interface names must not be in the canonical format (i.e. node-ethN where N is the port number of the interface) because the automatic assignment uses it.

addNode(name, **opts)

Adds a node to the network.

Parameters:

• name (str) – node name
• **opts (kwargs) – node options

Returns:

node name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addP4RuntimeSwitch(name, **opts)

Adds P4 runtime switch node to Mininet topology.

Parameters:

• name (str) – P4Runtime switch name
• **opts – switch options

Returns:

P4Runtime switch name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addP4Switch(name, **opts)

Adds P4 switch node to the network.

Parameters:

• name (str) – switch name
• opts (kwargs) – switch options

Returns:

P4 switch name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addRouter(name, **opts)

Adds a router node to the network.

Parameters:

• name (str) – router name
• **opts – router options

Returns:

router name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addSwitch(name, **opts)

Adds switch node to the network.

Parameters:

• name (str) – switch name
• **opts – switch options

Returns:

switch name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

addTask(name, exe, start=0, duration=0, enableScheduler=True, args=(), kwargs={})

Adds a task to the node.

Parameters:

• name (str) – node name
• exe (str or types.FunctionType) – executable to run (either a shell string command or a Python function)
• start (float) – task delay in seconds with respect to the network starting time.
• duration (float) – task duration time in seconds (if duration is lower than or equal to 0, then the task has no time limitation)
• enableScheduler (bool) – whether to automatically enable the TaskServer or not
• args (tuple or list) – positional arguments for the passed function
• kwargs (dict) – key-word arguments for the passed function

Note

This method can automatically enable the task scheduler (provided by the TaskServer) on the node with the socket lacated in the default path, if it has not been previously enabled.

addTaskFile(filepath, def_mod='p4utils.utils.traffic_utils')

Adds the tasks to the node.

Parameters:

• filepath (str) – tasks file path
• def_mod (str) – default module where to look for Python functions

The file has to be a set of lines, where each one has the following syntax:

<node> <start> <duration> <exe> [<arg1>] ... [<argN>] [--mod <module>] [--<key1> <kwarg1>] ... [--<keyM> <kwargM>]

Note

A non-default module can be specified in the command with --mod <module>.

addTofino(name, **opts)

Adds Tofino switch node to Mininet topology.

Parameters:

• name (str) – P4Runtime switch name
• **opts – switch options

Returns:

Tofino switch name.

Return type:

str

Warning

If a node with the same name is already present, this method will overwrite it.

areNeighbors(node1, node2)

Checks if two node are neighbors.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node

Returns:

True if node1 and node2 are neighbors, False otherwise.

Return type:

bool

deleteLink(node1, node2, key=None)

Delete link.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Note

If key is None, then the link with the lowest key value is considered.

deleteNode(name, remove_links=True)

Deletes node.

Parameters:

• name (str) – node name
• remove_links (bool) – remove all the incident links

describeP4Nodes()

Prints a description for the P4 nodes in the network.

disableArpTables()

Disables the static ARP entries for hosts in the same network.

disableCli()

Disables the Mininet client.

disableCpuPort(name)

Disables CPU port on switch.

Parameters:name (str) – P4 switch name

disableCpuPortAll()

Disables CPU port on all the P4 switches.

disableDebugger(name)

Disables debugger for the P4 switch.

Parameters:name (str) – P4 switch name

Note

For the default setting check out P4Switch.

disableDebuggerAll()

Disable debugger for all the P4 switches.

Note

For the default setting check out P4Switch.

disableDhcp(name)

Disables DHCP server in hosts.

Parameters:name (str) – host name Raises:Exception – if the specified node is not a host.

disableDhcpAll()

Disables DHCP for all the hosts.

disableGwArp()

Disables the static ARP entry in hosts for the gateway only.

disableLog(name)

Disables log for node (also for its task scheduler).

Parameters:name (str) – node name

disableLogAll()

Disables log for all the nodes (also for the task schedulers).

disablePcapDump(name)

Disables generation of .pcap files for the P4 switch.

Parameters:name (str) – name of the P4 switch

Note

For the default setting check out P4Switch.

disablePcapDumpAll()

Disables generation of .pcap files for all the P4 switches.

Note

For the default setting check out P4Switch.

disableScheduler(name)

Disables the task scheduler server for the node.

Parameters:name (str) – node name

disableSchedulerAll()

Disables the task scheduler server for all the nodes.

enableArpTables()

Enables the static ARP entries for hosts in the same network.

Note

This option is enabled by default.

enableCli()

Enables the Mininet client.

Note

This option is enabled by default.

enableCpuPort(name)

Enables CPU port on switch.

Parameters:name (str) – P4 switch name

Warning

This operation will create a new switch called sw-cpu. Should a node with the same name exist, then it would be overwritten.

enableCpuPortAll()

Enables CPU port on all the P4 switches.

Warning

This applies only to already defined switches. If other switches are added after this command, they won’t have any CPU port enabled.

enableDebugger(name)

Enables debugger for the P4 switch.

Parameters:name (str) – P4 switch name

Note

For the default setting check out P4Switch.

enableDebuggerAll()

Enable debugger for all the P4 switches.

Note

For the default setting check out P4Switch.

enableDhcp(name)

Enables DHCP server in hosts.

Parameters:name (str) – host name Raises:Exception – if the specified node is not a host.

enableDhcpAll()

Enables DHCP for all the hosts.

enableGwArp()

Enables the static ARP entry in hosts for the gateway only.

Note

This option is enabled by default.

enableLog(name, log_dir='./log')

Enables log for node (also for its task scheduler).

Parameters:

• name (str) – node name
• log_dir (str) – path to the log directory

enableLogAll(log_dir='./log')

Enables log for all the nodes (also for their task schedulers).

Parameters:log_dir (str) – path to the log directory

enablePcapDump(name, pcap_dir='./pcap')

Enables generation of .pcap files for the P4 switch.

Parameters:

• name (str) – P4 switch name
• pcap_dir (str) – where to save pcap files

Note

For the default setting check out P4Switch.

enablePcapDumpAll(pcap_dir='./pcap')

Enables generation of .pcap files for all the P4 switches.

Parameters:pcap_dir (str) – where to save .pcap files

Note

For the default setting check out P4Switch.

enableScheduler(name, path='/tmp')

Enables the task scheduler server for the node.

Parameters:

• name (str) – node name
• path (str) – directory where the socket file will be placed

enableSchedulerAll(path='/tmp')

Enables a task scheduler server for each node.

Parameters:path (str) – name of the directory where the socket files will be placed

execScript(cmd, out_file=None, reboot=True)

Executes the given command in the main namespace after the network boot.

Parameters:

• cmd (str) – command to execute
• out_file (str) – where to redirect stdout and stderr
• reboot (bool) – rerun the script every time all the P4 switches are rebooted.

getLink(node1, node2, key=None)

Returns link metadata dictionary.

Parameters:

• node1 (str) – name of first node
• node2 (str) – name of second node
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

(link, key) where link is a dict containing all

the information about the link and key is the id of the link between node1 and node2.

Return type:

tuple

Note

If key is None, then the link with the lowest key value is considered.

getNode(name)

Gets node information.

Parameters:node (str) – node name Returns:node metadata. Return type:dict

hasCpuPort(name)

Checks if the P4 Switch has a CPU port.

Parameters:name (str) – P4 switch name Returns:True if node has a CPU port, False otherwise. Return type:bool

hasScheduler(name)

Checks if a host has an active scheduler.

Parameters:name (str) – node name Returns:True if the node has an active scheduler, False otherwise. Return type:bool

hosts(sort=True, withInfo=False)

Returns hosts.

Parameters:

• sort (bool) – sort hosts alphabetically
• withInfo (bool) – retrieve node information

Returns:

list of (host [, info]).

Return type:

list

isHost(name)

Checks if node is a host.

Parameters:name (str) – node name Returns:True if node is a host, False otherwise. Return type:bool

isNode(name)

Checks if node exists.

Parameters:name (str) – node name Returns:True if node exists, False otherwise. Return type:bool

isP4RuntimeSwitch(name)

Checks if node is a P4Runtime switch.

Parameters:name (str) – node name Returns:True if node is a P4Runtime switch, else False. Return type:bool

isP4Switch(name)

Checks if the node is a P4 switch.

Parameters:name (str) – node name Returns:True if node is a P4 switch, False otherwise. Return type:bool

isRouter(name)

Checks if a node is a router.

Parameters:name (str) – node name Returns:True if node is a router, False otherwise. Return type:bool

isSwitch(name)

Checks if node is a switch.

Parameters:name (str) – node name Returns:True if node is a switch, False otherwise. Return type:bool

isTofino(name)

Checks if node is a Tofino switch.

Parameters:name (str) – node name Returns:True if node is a Tofino switch, else False. Return type:bool

l2()

Automated IP/MAC assignment strategy for already initialized links and nodes. All the devices are placed inside the same IPv4 network (10.0.0.0/16).

Assumes

• Each host is connected to exactly one switch.
• Only switches and hosts are allowed.
• Parallel links are not allowed.

Warning

Routers are not supported.

l3()

Automated IP/MAC assignment strategy for already initialized links and nodes. All the hosts have a different subnetwork that is shared with the fake IP address of the switch port they are connected to.

Assumes

• Each host is connected to exactly one switch.
• Only switches and hosts are allowed.
• Parallel links are not allowed.

Warning

Routers are not supported.

links(sort=False, withKeys=False, withInfo=False)

Returns links with no duplicated edges. Every link is listed exactly once.

Parameters:

• sort (bool) – sort links alphabetically
• withKeys (bool) – return link keys
• withInfo (bool) – return link info

Returns:

list of (src, dst [, key, info ]).

Return type:

list

mixed()

Automated IP/MAC assignment strategy for already initialized links and nodes. All the hosts connected to the same switch are placed in the same subnetwork. Different switches (even those linked together) are placed in different subnetworks.

Assumes

• Each host is connected to exactly one switch.
• Only switches and hosts are allowed.
• Parallel links are not allowed.

Warning

Routers are not supported.

nodes(sort=True, withInfo=False)

Returns all the nodes.

Parameters:

• sort (bool) – sort nodes alphabetically
• withInfo (bool) – retrieve node information

Returns:

list of (node [, info]).

Return type:

list

p4rtswitches(sort=True, withInfo=False)

Returns P4Runtime switches.

Parameters:

• sort (bool) – sort switches alphabetically
• withInfo (bool) – retrieve node information

Returns:

list of (p4runtimeswitch [, info]).

Return type:

list

p4switches(sort=True, withInfo=False)

Returns P4 switches.

Args:

sort (bool) : sort switches alphabetically withInfo (bool): retrieve node information

Returns:list of (p4switch [, info]). Return type:list

popLink(node1, node2, key=None)

Pops link.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

(link, key) where link is a dict containing all

the information about the link and key is the id of the link between node1 and node2.

Return type:

tuple

Note

If key is None, then the link with the lowest key value is considered.

popNode(name, remove_links=True)

Pops node.

Parameters:

• name (str) – node name
• remove_links (bool) – remove all the incident links

Returns:

node metadata.

Return type:

dict

printPortMapping()

Prints the port mapping of all the devices.

routers(sort=True, withInfo=False)

Return routers.

Parameters:

• sort (bool) – sort routers alphabetically
• withInfo (bool) – retrieve node information

Returns:

list of (router [, info]).

Return type:

list

setBw(node1, node2, bw, key=None)

Sets link bandwidth.

Parameters:

• node1 (str) – name of the fist node
• node2 (str) – name of the second node
• bw (float, int) – bandwidth (in Mbps)
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setBwAll(bw)

Sets bandwidth for all the links currently in the network.

Parameters:bw (float) – bandwidth (in Mbps)

Warning

This only sets the bandwidth of the links that have been already added to the topology: those added after this method is called will not meet this setting.

setCompiler(compilerClass=None, **kwargs)

Sets the default P4 compiler class and options.

Parameters:

• compilerClass (type) – compiler class to use for the compilation of P4 code
• **kwargs – key-word arguments to pass to the compiler object when it is first instantiated

Note

One can provide both compilerClass and **kwargs or only one of them (e.g. one may want to use the default compiler P4C and pass some parameters to it).

setDefaultRoute(name, default_route)

Sets the node’s default route.

Parameters:

• name (str) – name of the node
• default_route (str) – default route IP

setDelay(node1, node2, delay, key=None)

Sets link delay.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• delay (int) – transmission delay (in ms)
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setDelayAll(delay)

Sets delay for all the links currently in the network.

Parameters:delay (int) – transmission delay (in ms)

Warning

This only sets the delay of the links that have been already added to the topology: those added after this method is called will not meet this setting.

setGrpcPort(name, port)

Sets the gRPC port number for the P4Runtime switch.

Parameters:

• name (str) – name of the P4 runtime switch
• port (int) – gRPC port number

setIntfIp(node1, node2, ip, key=None)

Sets IP of node1’s interface facing node2 with the specified key.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• ip (str) – IP address/mask to configure
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setIntfMac(node1, node2, mac, key=None)

Sets MAC of node1’s interface facing node2 with the specified key.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• mac (str) – MAC address to configure
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setIntfName(node1, node2, intfName, key=None)

Sets name of node1’s interface facing node2 with the specified key.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• intfName (str) – name of the interface
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setIntfPort(node1, node2, port, key=None)

Sets port number of node1’s interface facing node2 with the specified key.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• port (int) – name of the interface
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setIpBase(ipBase)

Sets the network in which all the L3 devices will be placed if no explicit assignment is performed (e.g. assignment strategies or manual assignment).

Parameters:ipBase (str) – IP address / mask (e.g. 10.0.0.0/8)

Warning

Remember that setting the IP base won’t automatically change the already assigned IP. If you want to specify a different network, please use this method before any node is added to the network.

setLogLevel(logLevel)

Sets the log level for the execution.

Parameters:logLevel (str) – level of logging detail.

Possible logLevel values are the follwing (in decreasing order of detail):

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

setLoss(node1, node2, loss, key=None)

Sets link loss.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• loss (float) – packet loss rate (e.g. 0.5 means that 50% of packets will exeperience a loss)
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setLossAll(loss)

Sets loss for all the links currently in the network.

Parameters:loss (float) – packet loss rate (e.g. 0.5 means that 50% of packets will exeperience a loss)

Warning

This only sets the loss rate of the links that have been already added to the topology: those added after this method is called will not meet this setting.

setMaxQueueSize(node1, node2, max_queue_size, key=None)

Sets link max queue size.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• max_queue_size (int) – maximum number of packets the qdisc may hold queued at a time.
• key (int) – id used to identify multiple edges which link two same nodes (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

setMaxQueueSizeAll(max_queue_size)

Sets max queue size for all the links currently in the network.

Parameters:max_queue_size (int) – maximum number of packets the qdisc may hold queued at a time.

Warning

This only sets the max queue size of the links that have been already added to the topology: those added after this method is called will not meet this setting.

setNet(netClass=None, **kwargs)

Sets the default network class and options.

Parameters:

• netClass (type) – network class to use for the orchestration
• **kwargs – key-word arguments to pass to the network object when it is first instantiated

Note

One can provide both netClass and **kwargs or only one of them (e.g. one may want to use the default network P4Mininet and pass some parameters to it).

setP4CliInput(name, cli_input)

Sets the path to the command line configuration file for a Thrift capable P4 switch.

Parameters:

• name (str) – P4 switch name
• cli_input (str) – path to the command line configuration file

setP4Source(name, p4_src)

Sets the P4 source for the switch.

Parameters:

• name (str) – P4 switch name
• p4_src (str) – path to the P4 source file

setP4SourceAll(p4_src)

Sets the same P4 source for all the P4 switches.

Parameters:p4_src (str) – path to the P4 file

setP4SwitchId(name, id)

Sets P4 Switch ID.

Parameters:

• name (str) – P4 switch name
• id (int) – P4 switch ID

setPriorityQueueNum(name, queue_num)

Sets the queue_num for the ports of the P4 switch. :param name: P4 switch name :type name: str :param queue_num: Number of priority queues for each port :type queue_num: int

setSwitchClient(swclientClass=None, **kwargs)

Sets the default switch client class and options.

Parameters:

• swclientClass (type) – Thrift client class to use for the the control plane configuration
• **kwargs – key-word arguments to pass to the client object when it is first instantiated

Note

One can provide both swclientClass and **kwargs or only one of them (e.g. one may want to use the default client ThriftClient and pass some parameters to it).

setSwitchDpid(name, dpid)

Sets Switch DPID.

Parameters:

• name (str) – name of the P4 switch
• dpid (str) – switch DPID (16 hexadecimal characters)

Note

This method only applies to non P4 switches since P4 switches’ DPIDs are determined by their IDs.

setThriftPort(name, port)

Sets the Thrift port number for the P4 switch.

Parameters:

• name (str) – P4 switch name
• port (int) – Thrift port number

setTopologyFile(topoFile)

Sets the file where the topology will be saved for subsequent queries in the exercises.

Parameters:topoFile (str) – path to the topology database file

Note

The topology database is stored in ./topology.json by default.

startNetwork()

Starts and configures the network.

stopNetwork()

Stops the network.

stop_exec_scripts()

Stops all exec scripts.

switches(sort=True, withInfo=False)

Returns switches.

Parameters:

• sort (bool) – sort switches alphabetically
• withInfo (bool) – retrieve node information

Returns:

list of (switch [, info]).

Return type:

list

updateLink(node1, node2, key=None, **opts)

Updates link metadata dictionary. In fact, delete the node and create a new one with the updated information.

Parameters:

• node1 (str) – name of the first node
• node2 (str) – name of the second node
• key (int) – id used to identify multiple edges which link two same nodes (optional)
• **opts – link options to update (optional)

Returns:

key of the link between node1 and node2.

Return type:

int

Note

If key is None, then the link with the lowest key value is considered.

updateNode(name, **opts)

Updates node metadata dictionary. In fact, it deletes the node and creates a new one with the updated information.

Parameters:

• name (str) – node name
• **opts – node options to update (optional)

Returns:

node name.

Return type:

str