update documentation
Developer-only documentation was moved to DEVELOPING. Redundant usage
information was removed from oft.
diff --git a/DEVELOPING b/DEVELOPING
new file mode 100644
index 0000000..ff391e4
--- /dev/null
+++ b/DEVELOPING
@@ -0,0 +1,102 @@
+Overview
+++++++++
+
+ The directory structure is currently:
+
+ <oftest>
+ `
+ |-- oft
+ |-- doc
+ |-- src
+ | `-- python
+ | `-- oftest
+ |-- tests
+ | `-- 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
+ testutils.py: Test utilities
+ base_tests.py: Base test classes
+
+Important Notes
++++++++++++++++
+
+ 1. If you change any of the code generation scripts in
+ tools/munger/scripts you must re-run make -C tools/munger to
+ regenerate the OpenFlow message classes.
+
+Adding Your Own Test Cases
+++++++++++++++++++++++++++
+
+ Check the online tutorial:
+ http://openflow.org/wk/index.php/OFTestTutorial
+
+ It's suggested to use basic.py as example code for writing new tests.
+
+ 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. Most tests will inherit from oftest.base_tests.SimpleDataPlane.
+
+ 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.
+
+Submitting Patches
+++++++++++++++++++
+
+ Send a pull request on GitHub to floodlight/oftest.
+
+Other Info
+++++++++++
+
+ * Build doc with
+ + cd <oftest>/tools/munger
+ + make doc
+ Places the results in <oftest>/doc/html
+ If you have problems, check the install location doxypy.py and
+ that it is set correctly in <oftest>/doc/Doxyfile
+
+ * 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?
diff --git a/README b/README
index a8552bf..2f1a7da 100644
--- a/README
+++ b/README
@@ -1,19 +1,10 @@
OpenFlow Testing Framework
July, 2010
-Last updated March 2012
+Last updated January 2013
Copyright (c) 2010 The Board of Trustees of The Leland Stanford
Junior University
-Warning
-+++++++
-
- This is still experimental and it requires root privilege to
- control the dataplane ports. As a consequence, there may be
- risks to the machine on which this is running. Use caution.
-
- Please see Helpful Notes below.
-
License
+++++++
@@ -26,13 +17,6 @@
Other software referenced in this distribution is subject to its
respective license.
-Getting OFTest
-++++++++++++++
-
- You can check out OFTest with git with the following command:
-
- git clone git://github.com/floodlight/oftest
-
Introduction
++++++++++++
@@ -49,6 +33,16 @@
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
+++++++++++
@@ -69,9 +63,9 @@
Make sure the switch you want to test is running --
see (4) below for the reference switch example.
# ./oft --list
- # sudo ./oft --test-spec=Echo
+ # sudo ./oft basic.Echo
# sudo ./oft --verbose --log-file=""
- # sudo ./oft --test-spec=<mod> --platform=remote --host=...
+ # sudo ./oft basic --platform=remote --host=...
Longer Start
++++++++++++
@@ -105,15 +99,10 @@
This places files in <oftest>/src/python/oftest/src.
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. This is meant to
- allow you to test remote switches attempting to connect to a
- controller on a network accessible to the test host.
+ 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
@@ -143,11 +132,39 @@
oftest/tools/ovs-ctl. You will need to install a version of
openvswitch. See http://openvswitch.org/.
- 5. Run oft
- See Warning above; requires sudo to control the dataplane
+ 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
+++++++++++++++++++++++++++++++++++
@@ -176,113 +193,6 @@
that need to be ironed out. Please report any issues to
dtalayco@stanford.edu.
-
-OFT Command Line Options
-++++++++++++++++++++++++
-
- Here is a summary of the oft command line options. Use --help to see
- the long and short command option names.
-
- platform : String identifying the target platform
- controller_host : Host on which test controller is running (for sockets)
- controller_port : Port on which test controller listens for switch cxn
- port_count : Number of ports in dataplane
- base_of_port : Base OpenFlow port number in dataplane
- base_if_index : Base OS network interface for dataplane
- test_dir : Directory to search for test files (default .)
- test_spec : Specification of test(s) to run
- log_file : Filename for test logging
- list : Boolean: List all tests and exit
- debug : String giving debug level (info, warning, error...)
- verbose : Same as debug=verbose
-
-Overview
-++++++++
-
- The directory structure is currently:
-
- <oftest>
- `
- |-- oft
- |-- doc
- |-- src
- | `-- python
- | `-- oftest
- |-- tests
- | `-- 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
- testutils.py: Test utilities
-
- 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 change any of the code generation scripts in
- tools/munger/scripts you must re-run make -C tools/munger to
- regenerate the OpenFlow message classes.
-
- 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.
-
- 3. If tests dealing with VLANs fail unexpectedly then try installing
- pypcap (see Longer Start above).
-
-Adding Your Own Test Cases
-++++++++++++++++++++++++++
-
- Check the online tutorial:
- http://openflow.org/wk/index.php/OFTestTutorial
-
- 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
+++++++++++++++++
@@ -305,33 +215,3 @@
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
- If you have problems, check the install location doxypy.py and
- that it is set correctly in <oftest>/doc/Doxyfile
-
- * 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?
-
diff --git a/oft b/oft
index 1ca79fe..2fb60d4 100755
--- a/oft
+++ b/oft
@@ -4,91 +4,12 @@
OpenFlow test framework top level script
-This script is the entry point for running OpenFlow tests
-using the OFT framework.
+This script is the entry point for running OpenFlow tests using the OFT
+framework. For usage information, see --help or the README.
-The global configuration is passed around in a dictionary
-generally called config. The keys have the following
-significance.
-
-<pre>
- platform : String identifying the target platform
- controller_host : Host on which test controller is running (for sockets)
- controller_port : Port on which test controller listens for switch cxn
- test_dir : (TBD) Directory to search for test files (default .)
- test_spec : (TBD) Specification of test(s) to run
- log_file : Filename for test logging
- list : Boolean: List all tests and exit
- debug : String giving debug level (info, warning, error...)
-</pre>
-
-See config_defaults below for the default values.
-
-The following are stored in the config dictionary, but are not currently
-configurable through the command line.
-
-<pre>
- dbg_level : logging module value of debug level
- port_map : Map of dataplane OpenFlow port to OS interface names
-</pre>
-
-Each test may be assigned a priority by setting the "priority" property
-in the class definition. For now, the only use of this is to avoid
-automatic inclusion of tests into the default list. This is done by
-setting the priority value less than 0. Eventually we may add ordering
-of test execution by test priority.
-
-To add a test to the system, either: edit an existing test case file (like
-basic.py) to add a test class which inherits from unittest.TestCase (directly
-or indirectly); or add a new file with the test case class. Preferably the
-file is in the same directory as existing tests, though you can specify the
-directory on the command line. The file should not be called "all" as that's
-reserved for the test-spec.
-
-TBD: To add configuration to the system, first add an entry to config_default
-below. If you want this to be a command line parameter, edit config_setup
-to add the option and default value to the parser. Then edit config_get
-to make sure the option value gets copied into the configuration
-structure (which then gets passed to everyone else).
-
-By convention, oft attempts to import the contents of a file by the
-name of $platform.py into the local namespace.
-
-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.
-
-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.
-
-The current model for test sets is basic.py.
-
-Default setup:
-
-The default setup runs locally using veth pairs. To exercise this,
-checkout and build an openflow userspace datapath. Then start it on
-the local host:
-<pre>
- sudo ~/openflow/regress/bin/veth_setup.pl
- sudo ofdatapath -i veth0,veth2,veth4,veth6 punix:/tmp/ofd &
- sudo ofprotocol unix:/tmp/ofd tcp:127.0.0.1 --fail=closed --max-backoff=1 &
-
-Next, run oft:
- sudo ./oft --debug=info
-</pre>
-
-Examine oft.log if things don't work.
-
-@todo Support per-component debug levels (esp controller vs dataplane)
-@todo Allow specification of priority to override prio check
-
-Current test case setup:
- File with the .py extension in the test directory are considered test files.
- Support a command line option --test-spec to choose the tests to run.
- Support test-spec "all" to specify all tests.
+To add a new command line option, edit both the config_default dictionary and
+the config_setup function. The option's result will end up in the global
+oftest.config dictionary.
"""
import sys