How to Use OFTest With Open vSwitch
		 ===================================

This document describes how to use the OFTest OpenFlow protocol
testing suite with Open vSwitch in "dummy mode".  In this mode of
testing, no packets travel across physical or virtual networks.
Instead, Unix domain sockets stand in as simulated networks.  This
simulation is imperfect, but it is much easier to set up, does not
require extra physical or virtual hardware, and does not require
supervisor privileges.

Prerequisites
-------------

First, build Open vSwitch according to the instructions in INSTALL.
You need not install it.

Second, obtain a copy of OFTest and install its prerequisites.  You
need a copy of OFTest that includes commit 406614846c5 (make ovs-dummy
platform work again).  This commit was merged into the OFTest
repository on Feb 1, 2013, so any copy of OFTest more recent than that
should work.

Testing OVS in dummy mode does not require root privilege, so you may
ignore that requirement.

Optionally, add the top-level OFTest directory (containing the "oft"
program) to your $PATH.  This slightly simplifies running OFTest later.

Running OFTest
--------------

To run OFTest in dummy mode, run the following command from your Open
vSwitch build directory:

    make check-oftest OFT=<oft-binary>

where <oft-binary> is the absolute path to the "oft" program in
OFTest.

If you added "oft" to your $PATH, you may omit the OFT variable
assignment:

    make check-oftest

By default, "check-oftest" passes "oft" just enough options to enable
dummy mode.  You can use OFTFLAGS to pass additional options.  For
example, to run just the basic.Echo test instead of all tests (the
default) and enable verbose logging:

    make check-oftest OFT=<oft-binary> OFTFLAGS='--verbose -T basic.Echo'

If you use OFTest that does not include commit 4d1f3eb2c792 (oft:
change default port to 6653), merged into the OFTest repository in
October 2013, then you need to add an option to use the IETF-assigned
controller port:

    make check-oftest OFT=<oft-binary> OFTFLAGS='--port=6653'

Interpreting OFTest Results
---------------------------

Please interpret OFTest results cautiously.  Open vSwitch can fail a
given test in OFTest for many reasons, including bugs in Open vSwitch,
bugs in OFTest, bugs in the "dummy mode" integration, and differing
interpretations of the OpenFlow standard and other standards.

Open vSwitch has not been validated against OFTest.  Please do report
test failures that you believe to represent bugs in Open vSwitch.
Include the precise versions of Open vSwitch and OFTest in your bug
report, plus any other information needed to reproduce the problem.

Contact 
-------

bugs@openvswitch.org
http://openvswitch.org/