README

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.

    There are two parts to running the test framework:

    * Building the python libraries that support the OF protocol
    * Running oft, the main entry point of the test framework

    Normally log output from oft is sent to the file oft.log, but
    can be redirected to the console by specifying --log-file="".

    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 -C tools/munger
         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 --platform=remote --host=...

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.  Build the OpenFlow Python message classes

        Important:  The OF version used by the controller is based on 
        the file in <oftest>/tools/pylibopenflow/include/openflow.h
        This is currently the 1.0 release file.

        make -C <oftest>/tools/munger

        This places files in <oftest>/src/python/oftest/src.

    3.  Edit configuration if necessary
        The default (local) platform uses 4 veth interface pairs and
        is only suitable for testing local software switches. To test
        hardware switches you will need to create an appropriate
        platform file. See the "Platforms" section below.

    4.  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/.

    5.  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.  With the local platform, you can use wireshark
    on the loopback interface as well as the dataplane veth 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 virtual
    ethernet interfaces and is suitable only for local software switches.

    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.