Page tree

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Deprecated in favor of ngsdn tutorial

The content of this page is outdated. Please check the NG-SDN Tutorial for a reference ONOS+P4 development environment:

P4 is a programming language to define the behavior of the data plane, it can be used to program targets such as software switches, reconfigurable ASICs or FPGA-based NICsFPGAs, or it can be used to formally specify the beahviour behavior of a fixed-function switch. P4 Runtime P4Runtime is a protocol to control at runtime the behavior of a P4-enabled data plane device. This page presents the support for P4 and P4 Runtime in ONOS, moreover we provide defined pipeline, for example, to install entries in a match+action table defined in the P4 program. This page provides steps to set up an environment to try ONOS with the Behavioral Model v2 (BMv2) (the reference P4 software switch). Support for P4 Runtime P4Runtime has been included in ONOS starting from the 1.11 (Loon) release.

This document assumes you are already familiar with ONOS, P4, P4 Runtime and BMv2. In other words, we assume you already know how to build and run ONOS, write a P4 program, build and run BMv2 with P4 Runtime supportP4Runtime and BMv2. If this is not the case, here's a list of pointers to get started:

Table of Contents

Developers Environment

To have a working simulator to use with the p4Runtime integration in ONOS you have two options:

  • download a prebuilt image of the machine
  • build your own machine

Download Pre-Built VM

Please download the VM provided here (mininet-p4.ova) and import it into VirtualBox by double clicking on the mininet-p4.ova file. The file is 3.55 gb so it might take some time to download depending on the speed of your network. 

The current machine hw spec is:

  • 8 GB of RAM
  • 4 cores

You can downsize the requirements on both cores and RAM to a minimum of

  • 4 GB of RAM
  • 2 cores

The machine username and password are:

titlepre-built VM username and password

Username: p4-mininet

Password: p4-mininet

Build Your own VM

The following steps will help you set up a development environment with Mininet, ONOS and BMv2 with P4Runtime support.

Before starting you need to download and set up a virtual machine with Mininet. The following instructions have been tested on the official Mininet 2.2.2 VM 64 Bit (Ubuntu 14.04), which you can find here.

In order to successfully build and  execute the required tools, we recommend the following minimum system configuration:

  •  4 GB of RAM
  • 2 cores
  • 8 GB free hard drive space (~4GB required to build P4 tools
    titleRecommended minimum system requirements
    titleONOS+P4 tutorial for beginners

    If this is the first time working with ONOS and/or P4, we strongly suggest you start from this tutorial:

    ONOS+P4 Tutorial for Beginners

    Table of Contents

    Table of Contents


    For an overview of how P4 and P4Runtime are supported in ONOS, please refer to this presentation (ONF Connect, December 2018):

    Click here to open the slides in a new window

    Video recording

    Widget Connector

    Features at a Glance

    By using ONOS, you'll be able to program and control a network comprising P4Runtime-enabled devices with all the benefits of a logically centralized SDN platform. The following features are currently supported:

    • Device discovery

    • P4 pipeline provisioning (at device connection)

    • Match-action table operations (via existing ONOS APIs such as FlowRule, FlowObjective, or Intent)
    • Action profile group/member operations (via Group ONOS API)
    • Controller packet-in and packet-out

    • Counter reads

    ONOS+P4 Developer VM

    We have created a special VM with all you need to test P4Runtime support in ONOS.

    You can use the following link to download an Open Virtual Appliance (OVA) package to be imported using VirtualBox or any other x86 virtualization system that supports this format.

    Click here to download the ONOS+P4 Developer VM (approx. 2.5 GB) (last updated 2019-05-16)

    Alternatively, you can use these instructions to build a VM locally using Vagrant.

    titleVM login credentials

    The VM comes with one user with sudo privileges. Use these credentials to log in:

    Username: sdn

    Password: rocks

    VM Contents

    The VM is based on Ubuntu 18.04 (cloud image) and contains the following software pre-installed:

    • ONOS
    • BMv2 simple_switch_grpc (P4 software switch with P4Runtime support)
    • p4c (P4 compiler)
    • Mininet (network emulator)

    Recommended System Requirements

    The VM is configured with 4 GB of RAM and 2 CPU cores, while the disk has size of approx. 8 GB. For a flawless experience, we recommend running the VM on a host system that has at least the double of resources.

    These are the recommended minimum requirements to be able to run a Mininet network with 1-10 BMv2 devices controlled by 1 ONOS instance. To emulate larger networks with multiple instances of ONOS (for example using, we recommend configuring the VM to use at least 4 CPU cores.

    VM Connectivity

    The VM comes with two network interfaces: a NATed interface that provides access to internet (eth0), and a host-only one (eth1). Once you are able to access the VM, use ifconfig (or your command of choice) to get the IP address of the host-only interface. You will need that later to SSH or access the ONOS GUI from your host system. Alternatively, if your host system supports zeroconf networking via mDNS (e.g. Bonjour in OS X, or Avahi in Linux) then you can use the hostname onos-p4-dev.local to access the VM. For example, to SSH into the VM's guest system:

    Code Block
    $ ssh sdn@onos-p4-dev.local

    Interface naming inside the VM is not guaranteed, please use your linux/networking/VirtualBox skills to figure out which interface is the host-only one. It should be the one named eth1, but that's not guaranteed. Similarly, make sure that VirtualBox is configured correctly such that the host-only interface can ping your host system.

    Important 2
    Without trying to tell you how to live your life, we do recommend for your convenience to set up SSH access to the VM (e.g. copying SSH keys for faster access), as you will need to use multiple terminal shells at the same time. The Ubuntu system in the VM comes already equipped with an SSH server on port 22.

    Known issues

    • VirtualBox shared folders are not mounted on startup on Ubuntu 18.04 even if "auto-mount" flag is set. To fix it 

      Code Block
      $ sudo systemctl edit --full vboxadd-service

      and remove systemd-timesync.service from the Conflicts= line, then reboot (source)


    This walkthrough demonstrates the necessary steps and commands to run a network of BMv2 devices in Mininet, controlled by ONOS using P4Runtime.


    In this example, the BMv2 devices will be configured with a sample P4 program that is provided by ONOS, named basic.p4.

    If not differently specified, the following commands have to be executed in a terminal shell of the VM.

    1. Build ONOS master

      Code Block
      $ cd ~/onos
      $ git clone
      Source ONOS's bash_profile. On your Mininet VM shell, type
       pull origin master
      $ bazel build onos
    2. Run ONOS

      Code Block
      $ export ONOS_APPS=drivers.bmv2,proxyarp,lldpprovider,hostprovider,fwd
      $ bazel run onos-local -- clean

      The variable ONOS_APPS indicates which ONOS applications to execute at ONOS boot. The list includes the BMv2 drivers (based on P4Runtime), the Proxy ARP application, the LLDP Link Provider, the Host Location Provider, and the Reactive Forwarding application. These applications combined together provide ONOS with capabilities to discover the topology (via injection of LLDP packets), the hosts (by intercepting and handling ARP requests) and to provide basic point-to-point connectivity.

    3. On a second terminal shell, access the ONOS command line:

      Code Block
      echo$ "source ~/onos/tools/dev/bash_profile" > ~/.bashrc
      source ~/.bashrc

      Important: replace .bashrc with your shell configuration profile (.bash_aliases.profile, etc.)

    4. Build and install P4 tools. We have prepared a special command to install everything in one shot! On your Mininet VM shell, simply type:

      Code Block

      This command will download, build and install BMv2 (with the simple_switch_grpc target), P4Runtime libraries, the P4 compiler p4c, the old BMv2 compiler p4c-bmv2, and all required dependencies (including protobuf and gRPC). This command takes approx. 20 minutes to complete with the minimum system configuration described before.
      if you run out of space on you mininet machine you can go inside the p4tools folder in the home directory:

      Code Block
      cd ~/p4tools

      then go in one of the local directories, e.g. p4rutnime

      Code Block
      cd p4runtime

      and clean the make artifacts with

      Code Block
      make clean
    5. Build the example P4 programs. On your Mininet VM shell, type:

      Code Block
      cd ~/onos/tools/test/p4src/p4-16/
      make all
    6. TBC

    Update P4Tools to latest version

    It might be needed to update the P4Tools to the latest version. Please run these commands one at a time in the same terminal window inside you machine. This process is the same for both the pre-built VM and any machine built from scratch.

    Code Block
    cd ~/onos/
    git pull
    cd ~

    Run the Developer Environment 

    Start Mininet, using BMv2 simple_switch_grpc target. 

    Go in the home directory:

    Code Block
    cd ~

    On your Mininet VM shell, type:

    Code Block
    sudo -E mn --custom $BMV2_MN_PY --switch onosbmv2 --controller remote,ip=


    1. onos localhost
    2. Check that all applications have been loaded successfully. On the ONOS command line, type:

      Code Block
      onos> apps -s -a

      You should see an output similar to this (depending on your startup apps defined in $ONOS_APPS)

      * 10 org.onosproject.drivers 1.13.0.SNAPSHOT Default Drivers
      * 35 org.onosproject.generaldeviceprovider 1.13.0.SNAPSHOT General Device Provider
      * 36 org.onosproject.protocols.grpc 1.13.0.SNAPSHOT gRPC Protocol Subsystem
      * 37 org.onosproject.protocols.p4runtime 1.13.0.SNAPSHOT P4Runtime Protocol Subsystem
      * 38 org.onosproject.p4runtime 1.13.0.SNAPSHOT P4Runtime Provider
      * 39 org.onosproject.drivers.p4runtime 1.13.0.SNAPSHOT P4Runtime Drivers
      * 42 org.onosproject.proxyarp 1.13.0.SNAPSHOT Proxy ARP/NDP
      * 44 org.onosproject.hostprovider 1.13.0.SNAPSHOT Host Location Provider
      * 45 org.onosproject.lldpprovider 1.13.0.SNAPSHOT LLDP Link Provider
      * 73 org.onosproject.pipelines.basic 1.13.0.SNAPSHOT Basic Pipelines
      * 119 org.onosproject.drivers.bmv2 1.13.0.SNAPSHOT BMv2 Drivers
      * 146 org.onosproject.fwd 1.13.0.SNAPSHOT Reactive Forwarding

    3. Start Mininet. On third VM terminal shell, type: 

      Code Block
      $ sudo -E mn --custom $BMV2_MN_PY --switch onosbmv2 --controller remote

      This will run a simple Mininet topology with 2 hosts connected to a BMv2 switch, to use a different topology please refer to the Mininet guide. The -E argument in sudo ensures that all environment variables are exported to the root user. $BMV2_MN_PY is used to point to the location of the Mininet custom file provided in ONOS. If successful, the output of the previous command should be similar to this:

      *** Creating network
      *** Adding controller
      *** Adding hosts:
      h1 h2
      *** Adding switches:
      *** Adding links:
      (h1, s1) (h2, s1)
      *** Configuring hosts
      h1 h2
      *** Starting controller
      *** Starting 1 switches
      Starting BMv2 target: simple_switch_grpc --device-id 0 -i 1@s1-eth1 -i 2@s1-eth2 --log-console -Lwarn --thrift-port 38148 --no-p4 -- --cpu-port 255 --grpc-server-addr
      [1] 2370

      *** Starting CLI:
      Info custom Mininet script

      When using the custom Mininet script, files related to the execution of the BMv2 switch are stored under /tmp. The name of these files depends on the switch name used in Mininet, e.g. s1, s2, etc. Example of these files are:

      bmv2-s1-grpc-port: contains the port used by the P4Runtime server executed by the BMv2 simple_switch_grpc instance named 's1'
      bmv2-s1-log: contains the BMv2 log
      bmv2-s1-netcfg.json: netcfg blob pushed to ONOS to discover the switch

      titlebm-* commands

      The VM comes with a number command aliases to aid in the debugging of BMv2 when executed as part of Mininet. These commands all take one parameter, the switch name used in Mininet, e.g. s1, s2, etc.

      Shows a live scrolling view of the given BMv2 switch instance log
      Access the BMv2 CLI, useful to dump table entries, etc.
      WARNING: this CLI uses the BMv2 Thrift-based APIs which capabilities overlap with P4Runtime (e.g. a table management is provided by both). For this reason, there could be inconsistency issues when using both APIs to write state to the switch. For example, if one tries to insert a table entry using Thrift, the same cannot be read using P4Runtime. In general, to avoid such issues, we suggest using this CLI only to read state, or to write state that is not managed by P4Runtime.
      Starts the BMv2 debugger
      Start the BMv2 nanomsg event logger client
    4. Check that the BMv2 switch has successfully connected to ONOS. On the ONOS command line, check the output of the following command.

      onos> devices

      id=device:bmv2:1, available=false, local-status=connected 9m33s ago, role=NONE, type=SWITCH,, hw=master, sw=master, serial=unknown, driver=bmv2:org.onosproject.pipelines.basic, locType=geo, name=device:bmv2:1, protocol=[p4runtime]

      From the output, we can see that the BMv2 switch is connected (available=true), along with information on the P4 program (pipeconf) deployed (driver=bmv2:org.onosproject.pipelines.basic) and on the protocol used to control the switch (protocol=[p4runtime]).

    5. Check that the 2 hosts can ping each other. On the Mininet command line, use the pingall command check the output:

      Code Block
      mininet> pingall
      *** Ping: testing ping reachability
      h1 -> h2
      h2 -> h1
      *** Results: 0% dropped (2/2 received)

    Update P4 tools to the latest version

    Since P4Runtime is a work-in-progress effort, we frequently update ONOS to support the most recent capabilities. Similarly, we update the version of the P4 tools (BMv2, P4Runtime, and p4c) in the VM. Use the following commands to update ONOS and the P4 tools to the latest version:

    Code Block
    $ cd ~/onos/
    $ git pull origin master
    $ onos-setup-p4-dev

    The onos-setup-p4-dev command will download and build the most recent version of the P4 tools. In case of errors, please remove any build artifact from previous executions:

    Code Block
    $ rm -rf ~/p4tools
    $ onos-setup-p4-dev