| 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 |
| 6633). 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 (6633 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. |