| OpenFlow Testing Framework |
| March, 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. |
| |
| 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. |
| |
| Quick Start |
| +++++++++++ |
| # cd <oftest>/tools/munger |
| # make install |
| # cd <oftest>/tests |
| # ./oft --list |
| # ./oft |
| # ./oft --test-spec=<mod> --debug=info --platform=remote --host=... |
| |
| Longer Start |
| ++++++++++++ |
| |
| 1. Pre-requisites: |
| * Root privilege on host |
| * Python 2.5. You can run platforms using eth interfaces with |
| Python 2.4. |
| * 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 install |
| This places files in <oftest>/src/python/oftest/src and then |
| calls setuptools to install on the local host |
| |
| 3. Edit configuration if necessary |
| Local platforms work with veth interface pairs and default to |
| four ports. You can adjust this a bit with the command line |
| parameters port_count, base_of_port and base_if_index. |
| |
| 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. |
| |
| 4. Start the switch to test |
| The switch must be running and actively attempting to |
| connect to the controller at the host/port specified above. |
| |
| 5. 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 |
| | `-- oft and files with test cases |
| `-- 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. |
| |
| Important Notes |
| +++++++++++++++ |
| |
| 1. If you edit any of the files in src/python/oftest or any of the |
| scripts in tools/munger/scripts, you MUST re-run make install. This |
| is easy to forget. |
| |
| 2. If your 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. |
| |
| Adding Your Own Test Cases |
| ++++++++++++++++++++++++++ |
| |
| You can: |
| |
| * Add cases to an existing file |
| * Add a new file |
| |
| If you add cases to an existing file, each case should be its own |
| class. It must inherit from unittest.TestCase or one of its |
| derivatives and define runTest (that's how test cases are discovered). |
| |
| If you add a new file, it must implement a top level function called |
| test_set_init which takes a configuration dictionary. See basic.py |
| for an example. The main point of this is to pass the port map |
| object to the test cases. But you can access any configuration |
| parameters this way. Each test case in the new file must derive |
| from unittest.TestCase. |
| |
| CONVENTIONS: |
| |
| The first line of the doc string for a file and for a test class is |
| displayed in the list command. Please keep it clear and under 50 |
| characters. |
| |
| |
| 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. |
| |
| |
| 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? |
| |