Updates to README.
diff --git a/README b/README
index 04a005a..9457398 100644
--- a/README
+++ b/README
@@ -13,35 +13,57 @@
framework that need to be ironed out. Please report any issues
to dtalayco@stanford.edu.
+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="".
+
Quick Start
+++++++++++
Make sure your switch is running and trying to connect to a
controller on the machine where you're running oft (normally port
- 6633). (We plan to add a script for the simple case of the SW
- switch running on the same host.)
+ 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 yuba:/usr/local/git/openflow-projects/oftest
- cd <oftest>/tools/munger
- make install
- cd ../../tests
- <start your OF switch to test>
- ./oft --list
- sudo ./oft --verbose --log-file=""
- sudo ./oft --test-spec=<mod> --debug=info --platform=remote --host=...
+ # git clone yuba:/usr/local/git/openflow-projects/oftest
+ # cd oftest/tools/munger
+ # make install
+ # cd ../../tests
+ Make sure the switch you want to test is running
+ # ./oft --list
+ # sudo ./oft
+ # sudo ./oft --verbose --log-file=""
+ # sudo ./oft --test-spec=<mod> --platform=remote --host=...
Longer Start
++++++++++++
1. Pre-requisites:
* An OF switch instance to test (see 4 below)
- * Root privilege on host
- * Python 2.5. You can run platforms using eth interfaces with
- Python 2.4.
- * oftest checked out (to a directory called <oftest> here)
+ * 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. You can run platforms using eth interfaces
+ with Python 2.4.
+ * Python setup tools (e.g.: sudo apt-get install python-setuptools)
+ * oftest checked out (called <oftest> here)
* scapy installed: http://www.secdev.org/projects/scapy/
+ 'sudo apt-get install scapy' should work on Debian.
* tcpdump installed (optional, but scapy will complain if it's
not there)
* Doxygen and doxypy for document generation (optional)
@@ -55,6 +77,7 @@
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
@@ -62,28 +85,33 @@
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.
+ --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.
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.
+ 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/tests
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. Make sure you
- use the same port for the switch as for oft.
+ 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