P4-Utils

P4-Utils is an extension to Mininet that makes P4 networks easier to build, run and debug. P4-utils is strongly inspired by p4app. Here we only provide a quick summary of the main information about P4-Utils. Check out the online documentation for more details about P4-Utils installation and usage.

Installation

In order to work, P4-Utils needs different programs coming from different sources as prerequisites. Since the installation process can be long and cumbersome, we provide different methods to make the deployment easier for the users:

• virtual machine configured to work with P4-Utils,
• manual installation using an installation script.

Virtual Machine

P4-Utils can run in a virtual machine to keep its environment separated from the rest of the system. Moreover, since P4-Utils is only available on Linux, other OS users can run it in a linux VM.

Running P4-Utils in a completely separated environment can be beneficial: in this way, installation and execution errors, that may arise, will not affect the whole system. For this reason, we recommend using a virtual machine.

You can choose to download and use one of our preconfigured VMs or to build it by yourself.

Manual Installation

If you have already installed all the requirements, you can simply install P4-Utils using the following commands:

git clone https://github.com/nsg-ethz/p4-utils.git
cd p4-utils
sudo ./install.sh

Attention!
The install script will use pip -e to install the project in editable mode, meaning that every time you update the files in this repository, either by pulling or doing local edits, the changes will automatically take place without the need of installing the package again.

If you want to uninstall run:

sudo ./uninstall.sh

This will remove all the scripts that were added to /usr/bin as well as uninstall the python package using pip.

Requirements

P4-Utils depends on the following programs in the given order:

1. PI LIBRARY REPOSITORY is required only for topologies with P4Runtime switches
2. BEHAVIORAL MODEL (bmv2)
3. p4c
4. Mininet
5. FRRouting is required only for topologies with routers

Since the installation process is long and cumbersome, we provide a Bash script that automatically installs the dependencies.

How does it work ?

P4-Utils creates virtual networks using Mininet and extended nodes that run P4-enabled switches. To create hosts, Mininet uses a bash process running in a network namespace, in order words, all the processes that run within the network namespaces have an isolated network stack. Switches are software-based switches like Open vSwitch, Linux Bridge, or BMV2 switches. Mininet uses virtual ethernet pairs, which live in the Linux kernel to connect the emulated hosts and switches.

For more information see:

• Mininet
• Linux Namespaces
• Virtual ethernet interfaces
• BMV2
• p4runtime-shell
• FRRouting
• OVS
• LinuxBridge

Features

P4-Utils adds on top of Mininet:

• A command-line launcher (p4run) to instantiate networks.
• A helper script (mx) to run processes in namespaces.
• Custom P4Host, P4Switch, P4RuntimeSwitch, FFRouter nodes (based on BMV2 and FRRouting).
• A very simple way of defining networks using JSON files (see p4app_example.json and related documentation).
• A very intuitive programmatic way of defining networks using a Python API (see related documentation).
• Enhances Mininet command-line interface by adding useful commands to manage P4 switches.
• Saves the topology information in an object that can be loaded and queried (see related documentation).
• Re-implementation of the runtime_CLI and simple_switch_CLI as Python objects to use in controller code.
• Re-implementation of the p4runtime-shell as Python objects to use in controller code.