Installing and setting up OpenFlow tools

From Compunet Wiki

Jump to: navigation, search

This tutorial describes how to install a complete environment for experimenting with OpenFlow switches in an emulated network.



As of May 2014, OpenFlow-related software is continuously evolving at a rapid pace. Unfortunately, many OpenFlow-related software pieces are not officially packaged, therefore the procedure below often accesses development repositories in order to fetch the most current source trees. As a consequence, things are not unlikely to break from one day to another.

In order to help cope with this everchanging world, for some steps an additional command is provided which explicitly specifies how to get exactly the same source tree that was used when writing this tutorial. These commands are optional and marked with a pin icon . Using them should ensure a reasonably error-free build and installation process (hopefully...). Using the pinned commands results in a setup aligned to the following software releases:

Software releases as of May 19th, 2014

  • Mininet: 2.1.0+
  • OpenFlow software switch (ofdatapath, ofprotocol): 1.3.0
  • Open vSwitch: 2.3.90 (OF versions 0x1:0x1)
  • Reference controller (ovs-controller): 2.0.1
  • POX: 0.2.0 (carp)
  • Ryu: 3.9
  • Wireshark OpenFlow dissector: N/A


This tutorial assumes the following working setup (please note that the same procedure may work well also with other Linux releases or distributions):

  • An installed and freshly updated Ubuntu 14.04 (trusty) 64 bit
    (the last software update for this tutorial was installed on May 19th, 2014)

The tutorial assumes that only the base installation has been performed, and no additional packages have been subsequently installed. As such, the steps in this tutorial are particularly suitable for being applied inside a virtual machine.


It should be safe to install the following software components in an arbitrary order. Yet, it is advised to follow the order in which they are listed in this tutorial.

Installing Mininet

This part of the procedure has been derived from [1]. It assumes that Mininet is available at [2].

sudo apt-get install -y git gcc make socat psmisc xterm ssh iperf iproute telnet \
                        python-setuptools cgroup-bin ethtool help2man pyflakes pylint pep8

As an alternative to the steps below, the latest Mininet source code (master branch) can be downloaded from here (not recommended).

git clone git://
cd mininet
 git checkout 5797f5852ec2edf31ce3e0986b6ba15e95ecfd37
sudo make install
cd ..

Installing OpenFlow 1.3 software switch (CPqD)

This procedure assumes that the implementation of an OpenFlow 1.3 compatible software switch is available at [3].

sudo apt-get install -y git-core autoconf automake autotools-dev pkg-config \
                        make gcc g++ libtool libc6-dev cmake libpcap-dev libxerces-c2-dev  \
                        unzip libpcre3-dev flex bison libboost-dev

Unfortunately, we need to downgrade bison in order to get NetBee to compile correctly.

wget -nc \
sudo dpkg -i bison_2.5.dfsg-2.1_amd64.deb libbison-dev_2.5.dfsg-2.1_amd64.deb
rm bison_2.5.dfsg-2.1_amd64.deb libbison-dev_2.5.dfsg-2.1_amd64.deb

We then need to compile and install NetBee as a prerequisite.

wget -nc
cd nbeesrc-jan-10-2013/src
cmake .
sudo cp ../bin/libn*.so /usr/local/lib
sudo ldconfig
sudo cp -R ../include/* /usr/include/
cd ../..

Now coming to the actual compile/install. As an alternative to the git-based steps below, the latest ofsoftswitch13 source code (master branch) can be downloaded from here (not recommended).

git clone
cd ofsoftswitch13
 git checkout d174464dcc414510990e38426e2e274a25330902
sudo make install
cd ..

Installing Open vSwitch

The OpenFlow kernel module should already be compiled in and, as stated in [4], is 99% compatible with the one provided by the openvswitch-datapath-dkms package (which, instead, fails to build).

This procedure describes how to install Open vSwitch from the source code available at [5]. As an alternative, the whole source code tree (master branch) can be downloaded from here (not recommended).

git clone
cd ovs
 git checkout 5a87054c2d832d0e10b30a1f223707acb8efbeb7

Notice: applying the following patch may no longer be required if a recent enough version of Open vSwitch has been checked out.

A sanity check in the current source code of Open vSwitch [6], [7] prevents installation of flow entries with a pop_mpls action that re-applies Ethernet type 0x8847 (MPLS). On the other hand, the intended behavior of action pop_mpls, which is to leave the Ethernet type of a packet unchanged unless the last label is being popped [8], does not seem to be correctly implemented, because the Ethernet type is always set by a pop_mpls. This in turn makes it impossible to pop a single MPLS label from a stack of at least two labels, because the Ethernet type 0x8847 (MPLS) should either be retained, which the current implementation does not do, or be set again to 0x8847 (MPLS), which the current implementation forbids. Interestingly, apart from the aforementioned sanity check, in accordance with what is officially documented [9] the rest of the Open vSwitch code is already designed to support stacks of at most 3 labels [10], therefore a small patch that removes the sanity check is all that is required to get full support for stacks of 3 MPLS labels. As a reassuring fact, the same patch has been independently proposed on the ovs-dev mailing list: [11].

wget -O - | patch -p1
sudo make install

We also need to set up some system-wide scripts in order to correctly start the switch.

mkdir openvswitch-switch
dpkg-deb -x openvswitch-switch_2.0.1+git20140120-0ubuntu2_amd64.deb openvswitch-switch/
sudo cp openvswitch-switch/etc/init.d/openvswitch-switch /etc/init.d
sudo mkdir -p /usr/share/openvswitch/scripts
sudo ln -s /usr/local/share/openvswitch/scripts/ovs-lib /usr/share/openvswitch/scripts
sudo ln -s /usr/local/sbin/ovs-vswitchd /usr/sbin
sudo ln -s /usr/local/sbin/ovsdb-server /usr/sbin
sudo update-rc.d openvswitch-switch defaults
cd ..

Installing controllers

Reference ovs controller

This simple controller enables switches to perform MAC learning.

sudo apt-get install -y openvswitch-controller

ovs-controller should be managed by Mininet, therefore we need to disable it system-wide:

sudo /etc/init.d/openvswitch-controller stop
sudo update-rc.d -f openvswitch-controller disable

Warning: this package has some dependencies on other packages which will install a different (older) version of some of the ovs tools, thus overriding other tools used by the Open vSwitch setup. However, these (older) tools will be installed to standard system paths like /usr/bin and /usr/sbin, whereas the more up-to-date counterparts are installed to /usr/local/bin and /usr/local/sbin. The default setting of the PATH environment variable in Ubuntu should be such that the more up-to-date versions are considered first, but beware of this chance of conflict.


This procedure assumes that POX is available at [12]. As an alternative to the step below, the latest POX source code (master branch) can be downloaded from here.

git clone
cd pox
 git checkout bab636bc89584b3bb2baaa5bc766be82fb81d1b2
cd ..


This procedure assumes that Ryu is available at [13]. Alternatively, the latest source tree (master) branch can be downloaded from here (not recommended).

sudo apt-get install -y python-{pip,dev,repoze.lru,ecdsa}
git clone git://
cd ryu
 git checkout f27768650ee4e3f3bd7d932ab0179833e67c3194

Warning: the following installation command requires downloading some components from the Internet

sudo python ./ install
cd ..

Ryu test tool

As documented here, Ryu makes available a test tool that automates the tasks required to verify the status of support of the OpenFlow specification by an OpenFlow switch software implementation. The tool executes flow entry registrations and injects packets according to a test pattern file. The result is compared against an expected processing result described in the test pattern file itself.

This tool is compatible with the FlowMod message specified in OpenFlow version 1.3.

As a sample test pattern, the source tree of Ryu offers a test pattern file to check if each parameter that can be specified in the match/actions of OpenFlow 1.3 FlowMod messages works properly. This test pattern file exploits the following network topology:

Network topology used in the sample test pattern file provided with Ryu.

The sample test pattern essentially repeats the following steps for a variety of different test packets and match conditions:

  • sends an OFPT_FLOW_MOD message to install a flow entry on the switch under test (the top one in the figure) that has a particular match condition (the one for which support is being tested) and that bounces matched packets back to the auxiliary switch;
  • sends a OFPT_FLOW_MOD message to instruct the auxiliary switch to send any packets received from the switch under test to the controller, encapsulated in OFPT_PACKET_IN messages;
  • uses an OFPT_PACKET_OUT message to solicit the auxiliary switch (the bottom one in the figure) to send a test packet with appropriate contents to the switch under test;
  • expects to receive an OFPT_PACKET_IN message at the controller, coming from the auxiliary switch and containing the test packet sent at the previous step, unmodified.

The test pattern can be started by following this procedure.

Use ovs (Open vSwitch) or cpqd (userspace ofdatapath switch) in the following command line to select the SWITCH_TYPE to be used.

cd ryu/ryu/tests/switch
sudo ./ --switch SWITCH_TYPE   # ovs or cpqd
Note: it may be the case that running the above Python script results in a "cannot import name Link" error. In this case, try applying this patch to file and running the script once again.

Just disregard the error message about the inability to contact the remote controller. Once the virtual network has been started, type either one of the following commands at the Mininet prompt:

mininet> c0 ryu-manager --test-switch-dir of13
 # or, if you want to run the test in a separate window:
mininet> c0 xterm -e "ryu-manager --test-switch-dir of13; bash"

Installing Wireshark OpenFlow dissector

The following steps describe the installation procedure for the Wireshark OpenFlow dissector available at [14]. Another dissector is also available at [15], but its installation procedure is not described here. As a rule of thumb, be aware that native Wireshark dissectors are always to be favoured, since they are usually more stable and feature-rich. At the time of writing this guide, an OpenFlow dissector is due to appear in release 1.12 of Wireshark, for which development sources are already available.

sudo apt-get install -y wireshark tshark libgtk2.0-dev scons mercurial libglib2.0-dev \
                        libwiretap-dev libwireshark-dev

As an alternative to the step below, the source code of the Wireshark OpenFlow dissector can be downloaded from here (not recommended).

hg clone
cd of-dissector
 hg update -r 3f3f190220e54af25bd233020c461ab6a9bfb45c
cd src
export WIRESHARK=/usr/include/wireshark
WSDIR=`find /usr/lib -type d -name 'libwireshark*' | head -1`
sudo cp $WSPLUGDIR

Last, put appropriate coloring rules and color filters in place.

mkdir -p ~/.wireshark
wget -O ~/.wireshark/colorfilters

Cleaning up

For the correct operation of the software listed above, it is required that a few additional operations are accomplished on the installation machine.

Warning: the following cleanup steps also disable the Network Manager, because it would otherwise interfere with the setup of virtual interfaces in Mininet networks. System-wide network configurations (e.g., interfaces with statically configured IP addresses) must be moved to file /etc/network/interfaces. Failure to do so will result in loss of connectivity for the host machine.
sudo apt-get purge -y avahi-daemon
sudo sh -c "echo manual > /etc/init/network-manager.override"
sudo stop network-manager

If you have moved the configuration of network interfaces to /etc/network/interfaces, as advised above, you may want to refresh their status in order to recover Internet connectivity:

sudo ifdown -a
sudo ifup -a


For a faster setup, this section recollects a few key steps and tools to accomplish the above procedures.

Almost all the required source trees, as well as a few additional files, can be downloaded as a single package here:

(~58MB, last updated on May 19th, 2014)

All the Ubuntu packages required to set up the OpenFlow environment can be installed with the following single command:

sudo apt-get install -y git git-core \
                        autoconf automake autotools-dev pkg-config make gcc g++ socat \
                        psmisc xterm ssh iperf iproute telnet \
                        cgroup-bin ethtool help2man pyflakes pylint pep8 \
                        libtool libc6-dev cmake libpcap-dev libxerces-c2-dev unzip \
                        libpcre3-dev flex bison libboost-dev \
                        openvswitch-controller \
                        python-{setuptools,pip,dev,repoze.lru,ecdsa} \
                        wireshark tshark libgtk2.0-dev scons mercurial libglib2.0-dev \
                        libwiretap-dev libwireshark-dev
Personal tools