OpenFlow Testing Framework
July, 2010
Last updated January 2013
Copyright (c) 2010 The Board of Trustees of The Leland Stanford
Junior University
License
+++++++
The software included with this distribution is subject to the
OpenFlow Switching License as given in the included file LICENSE.
Details are also available at:
http://www.openflow.org/wp/legal
Other software referenced in this distribution is subject to its
respective license.
Introduction
++++++++++++
This test framework is meant to exercise a candidate OpenFlow
switch (the device/switch under test, DUT or SUT). It provides a
connection like a controller to which the switch connects and it
controls data plane ports, sending and receiving packets, which
should be connected to the switch.
For information on writing new tests or making improvements to
the test framework see the file DEVELOPING.
Getting OFTest
++++++++++++++
You can check out OFTest with git with the following command:
git clone git://github.com/floodlight/oftest
Quick Start
+++++++++++
You need to have Python and Scapy installed on your system.
See 'Pre-requisites' below.
Make sure your switch is running and trying to connect to a
controller on the machine where you're running oft (normally port
6653). See below regarding run_switch.py for a script that starts
up a software switch on the test host.
Currently, switches must be running version 1.0 of OpenFlow.
# git clone git://github.com/floodlight/oftest
# cd oftest
Make sure the switch you want to test is running --
see (4) below for the reference switch example.
# ./oft --list
# sudo ./oft basic.Echo
# sudo ./oft --verbose --log-file=""
# sudo ./oft basic -i 1@veth1 -i 2@veth3
Longer Start
++++++++++++
1. Pre-requisites:
* An OF switch instance to test (see 4 below)
* Root privilege on host running oft
* Switch running OpenFlow 1.0 and attempting to connect
to a controller on the machine running oft.
* Python 2.5 or 2.6. You can run platforms using eth interfaces
with Python 2.4. Python 2.7 may work.
* oftest checked out (called <oftest> here)
* scapy installed: http://www.secdev.org/projects/scapy/
'sudo apt-get install scapy' should work on Debian.
* pypcap installed: http://code.google.com/p/pypcap/ (optional)
'sudo apt-get install python-pypcap' should work on Debian.
Tests using VLAN tags may fail without pypcap.
* tcpdump installed (optional, but scapy will complain if it's
not there)
* Doxygen and doxypy for document generation (optional)
* lint for source checking (optional)
2. Start the switch to test
The switch must be running and actively attempting to
connect to a controller on the test host at the port number
used by oft (6653 by default, or specified as --port=<n> as
an argument to oft).
If you're new to the test environment and want to check its
sanity, you can do the following. This requires that
your host kernel supports virtual ethernet interfaces. This
is best done in a window separate from where you will run oft.
4A. Check out openflow (preferably at the same level as oftest):
git clone git://openflowswitch.org/openflow.git
4B. cd openflow; ./boot.sh; ./configure; make
4C. cd ../oftest
4D. Run the switch startup script:
sudo ./run_switch.py; Now you can run oft (see below).
4F. Use --help to see command line switches. If you use a port
number other than the default, make sure you use the same
one for the switch as for oft.
4E. Use control-C to terminate the switch daemons.
4F. To clean up the virtual ethernet interfaces, use
sudo rmmod veth
New tools allow you to run an OVS instance as well. See
oftest/tools/ovs-ctl. You will need to install a version of
openvswitch. See http://openvswitch.org/.
3. Run oft (requires sudo to control the dataplane)
cd <oftest>
sudo ./oft --help
Important Notes
+++++++++++++++
1. If you're running into issues with transactions, and it appears that
OpenFlow messages aren't quite right, start by looking at any length
fields in the packets. You can use wireshark on the loopback interface
as well as the dataplane ethernet interfaces.
2. If tests dealing with VLANs fail unexpectedly then try installing
pypcap (see Longer Start above).
Platforms
+++++++++
The "platform" is a configuration file (written in Python) that
tells OFTest how to send packets to and receive packets from the
dataplane of the switch.
The default platform uses Linux ethernet interfaces and is configured with
the -i option. Pass the option as "-i ofport@interface", for example
"-i 1@eth1". If no -i options are given the the default configuration
uses veths and is compatible with the refrence switch.
You can add your own platform, say gp104, by adding a file gp104.py to the
platforms directory that defines the function platform_config_update and then
use the parameter --platform=gp104 on the command line. You can also use the
--platform-dir option to change which directory is searched.
IMPORTANT: That file should define a function platform_config_update which
takes a configuration dictionary as an argument and updates it for the
current run. In particular, it should set up config["port_map"] with
the proper map from OF port numbers to OF interface names.
Helpful Note: Recovering From Crash
+++++++++++++++++++++++++++++++++++
If the test script, oft, becomes unresponsive, you may find that
^C does not break out of the script. In this case you have two
options:
* Use ^Z to interrupt the script and return to the shell prompt.
* Start another terminal window to the same machine.
In either case, you then need to kill the process that is hung.
Use the following commands:
me@host> ps aux | grep oft
root 4 0.0 S< Jul07 0:00 [ksoftirqd/0]
...
root 14066 3.2 Tl 09:27 0:00 python ./oft ...
me 14074 0.0 R+ 09:28 0:00 grep oft
me@host> sudo kill -9 14066
where 14066 is the process ID of the hung process. (Replace it
with the PID for your process.)
This is still preliminary work and there are bugs in the framework
that need to be ironed out. Please report any issues to
dtalayco@stanford.edu.
Using CentOS/RHEL
+++++++++++++++++
CentOS/RHEL have two challenges: they are very tied to Python 2.4
(and Scapy requires Python 2.5 for its latest version) and they
require a kernel upgrade to use veth pairs for local platform
testing.
If you only need to control eth interfaces for a remote platform,
you can use CentOS/RHEL without major disruption. The key is to
download scapy-1.2 from the following link:
wget http://hg.secdev.org/scapy/raw-file/v1.2.0.2/scapy.py
See: http://www.dirk-loss.de/scapy-doc/installation.html#installing-scapy-v1-2
for more info.
Copy scapy.py to /usr/lib/python2.4/site-packages
If you hit an error related to importing scapy.all, you just need
to change the import to refer to scapy (not scapy.all). See
examples in parse.py for example.