README

OpenFlow Testing Framework
February, 2010

Warning
+++++++

This is still experimental and it requires root privilege to
control the dataplane ports.  As a consequence, there are
some serious risks to the machine on which this is running.
Use caution.

Quick Start
+++++++++++

    1.  Pre-requisites:
        * Python 2.5 (or so)
        * oftest checked out (called <oftest> here)
        * scapy installed:  http://www.secdev.org/projects/scapy/
        * 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.

        * cd <oftest>/tools/munger
        * make
        This places files in <oftest>/src/python/oftest/src

    3.  Install with setup (currently not required)
        * make install
        This runs setuptools on the generated source.  It requires
        that setuptools be installed and the user have sudo rights.

    4.  Edit configuration
        Starting from remote.py as a simple example, you can add your
        own <platform>.py file and then have it imported with
        --platform=<platform> on the command line.

    5.  Start the switch to test
        The switch must be running and actively attempting to 
        connect to the controller at the host/port specified above.

    6.  Run oft
        See Warning above; requires sudo to control the dataplane
        * cd <oftest>/tests
        * sudo ./oft --help

Overview
++++++++

    The directory structure is currently:

     <oftest>
         `
         |-- doc
         |-- src
         |   `-- python
         |       `-- oftest
         |-- tests
         `-- tools
             |-- munger
             `-- pylibopenflow

    The tools directory is what processes the OpenFlow header
    files to produce Python classes representing OpenFlow messages.
    The results are placed in src/python/oftest and currently
    include:

        message.py:      The main API providing OF message classes
        error.py:        Subclasses for error messages
        action.py:       Subclasses for action specification
        cstruct.py:      Direct representation of C structures in Python
        class_maps.py:   Addition info about C structures

    In addition, the following Python files are present in 
    src/python/oftest:

        controller.py:   The controller representation
        dataplane.py:    The dataplane representation
        action_list.py:  Action list class
        netutils.py:     e.g., set promisc on sockets
        ofutils.py:      Utilities related to OpenFlow messages
        oft_assert.py:   Test framework level assertion

    Tests are run from the tests directory.  The file oft is the
    top level entry point for tests.  Try ./oft --help for some more.


Other Info
++++++++++

    * Build doc with
      + cd <oftest>/tools/munger
      + make doc
    Places the results in <oftest>/doc/html

    * Run lint on sources
      + cd <oftest>/tools/munger
      + make lint
    Places results in <oftest>/lint/*.log
    The file controller.log currently has some errors indicated


To Do
+++++

    * Need to have an overview of the components of the test, how they
      connect and how they are managed by the test framework.
    * See the Regression Test component on trac:
      http://www.openflowswitch.org/bugs/openflow
      http://www.openflowswitch.org/bugs/openflow/query?component=Regression+test+suite

    * Make the framework work with OF versions other than 1.0?