README.md: Complete rewrite of README
- Add some documentation from the archived OpenFlow website, found
here:
http://archive.openflow.org/wk/index.php/OFTestTutorial
- Add some documentation from the OpenFlow Hub website, found here:
http://www.openflowhub.org/display/OFTest
- Reformat as Markdown
- Remove copyright, as it's duplicated in 'LICENSE'
- Remove old or irrelevant sections
- Resolve #152, "Running OFTest on a different board"
Signed-off-by: Stephen Finucane <stephenfinucane@hotmail.com>
diff --git a/README b/README
deleted file mode 100644
index b5f810a..0000000
--- a/README
+++ /dev/null
@@ -1,196 +0,0 @@
-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
- 6653). 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 (6653 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.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8790d26
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
+OFTest OpenFlow Testing Framework
+
+---
+
+# Introduction
+
+OFTest is a Python based OpenFlow switch test framework and collection of test cases. It is based on unittest, which is included in the standard Python distribution.
+
+This document is meant to provide an introduction to the framework, discuss the basics of running tests and to provide examples of how to add tests.
+
+For information on writing new tests or making improvements to the test framework see the file [DEVELOPING](DEVELOPING.md).
+
+---
+
+# How It Works
+
+OFTest is meant to exercise a candidate OpenFlow switch (henceforth the device under test (DUT) or switch under test (SUT)). Below is the "horseshoe" disagram for OFTest that demonstrates the interaction between OFTest and SUT.
+
+
+
+As you can see, the SUT is in the middle. The test fixture, the OFTest server, connects to both the control plane and the data plane of the SUT. It coordinates OpenFlow commands with data plane stimulus and monitoring.
+
+Some additional info on OFTest:
+
+ * OFTests starts with the very basics of OpenFlow, but provides a framework for development of more complicated tests.
+ * It was used as the primary vehicle for validating OpenFlow 1.1 (see the `oft-1.1` branch in the Git repository).
+ * A prototype implementation of an OpenFlow 1.1 switch, OFPS, was implemented in the same framework as OFTest (also in the `oft-1.1` branch).
+
+---
+
+# 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 `6653`).
+
+ cd oftest
+ ./oft --list
+ sudo ./oft basic.Echo
+ sudo ./oft --verbose --log-file=""
+ sudo ./oft basic -i 1@veth1 -i 2@veth3
+
+---
+
+# Extending OFTest
+
+We welcome any kind of patch. Send all patches as pull requests to `floodlight/oftest`. We recommend you check out the [CONTRIBUTING.md] document for ideas and requirements around patches.
+
+---
+
+# Longer Start
+
+## Configure Pre-requisites
+
+The following software is required to run OFTest:
+
+ * Python 2.7
+ * Scapy
+ * pypcap (optional - VLAN tests will fail without this)
+ * tcpdump (optional - Scapy will complain if it's missing)
+ * Doxygen and doxypy (optional - for documentation generation)
+ * PyLint (optional - for source checking)
+
+Most of these can be installed using your package manager. For example:
+
+ sudo yum install python # for RHEL-based distros
+ sudo apt-get install scapy # for Debian-based distros
+
+You will also need an OpenFlow-compliant switch instance to test. This switch must be running OpenFlow 1.0+ and attempting to connect to a controller on the machine running `oft`.
+
+Finally root/sudo privilege is required on the host, in order to run `oft`.
+
+## Start the Switch
+
+The switch must be running and actively attempting to connect to a controller on the test host at the port number used by oft (`6653` 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.
+
+ 1. Check out OpenFlow (preferably at the same level as oftest):
+
+ git clone git://openflowswitch.org/openflow.git
+
+ 2. Build OpenFlow:
+
+ cd openflow
+ ./boot.sh
+ ./configure; make
+ cd ../oftest
+
+ 4. Run the switch startup script:
+
+ sudo ./run_switch.py
+
+## Run OFTest
+
+Now you can run `oft` (see below). Use `--help` to see command line switches.
+
+ cd <oftest>
+ sudo ./oft --help
+
+If you use a port number other than the default, make sure you use the same one for the switch as for oft. For example, to run the `basic` collection of tests:
+
+ sudo ./oft basic -i 1@veth1 -i 2@veth3
+
+Once you're finished, use `Ctrl-C` to terminate the switch daemons. 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 [Open vSwitch](http://openvswitch.org/) for this to work.
+
+---
+
+# Configuring OFTest
+
+## 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.
+
+### `eth`
+
+The default platform, `eth`, uses Linux Ethernet interfaces and is configured with the `-i` option (or `--interface`). Pass the option as `-i ofport@interface`, for example `-i 1@eth1`. If no `-i` options are given the the default configuration uses vEths for backwards-compatibility with the original OpenFlow reference switch.
+
+### `remote`
+
+Another common platform, `remote`, provides support for testing of switches on a different host. This can be useful for cases where interfaces are not available on one host (i.e. they're not bound to a Linux interface driver) or where OFTest cannot run on the same host (unsupported OS, missing software, etc.).
+
+This can be enable by modifying the `platforms/remote.py` file to point to 4 NICs on the host running OFTest, like so:
+
+ remote_port_map = {
+ 23 : "eth2", # OpenFlow port 23 of the switch is connected to physical port on the server eth2
+ 24 : "eth3", # OpenFlow port 24 of the switch is connected to physical port on the server eth3
+ 25 : "eth4",
+ 26 : "eth5"
+ }
+
+## Passing Parameters to Tests
+
+There is a facility for passing test-specific parameters into tests that works as follows. On the command line, give the parameter
+
+ --test-params="key1=17;key2=True"
+
+Currently the keys used control whether VLAN tagged packets are used and whether VLAN tag stripping should be included as an action. These parameters include:
+
+ vid=N: Use tagged packets with VLAN id of N
+ strip_vlan=bool: If True, add the strip VLAN tag action to the packet test
+
+---