-
-Secure operation over SSL
--------------------------
-
-The instructions above set up Open vSwitch for operation over a
-plaintext TCP connection. Production use of Open vSwitch should use
-SSL[*] to ensure confidentiality and authenticity of traffic among
-switches and controllers. The source must be configured with
---enable-ssl=yes to build with SSL support.
-
-To use SSL with Open vSwitch, you must set up a public-key infrastructure
-(PKI) including a pair of certificate authorities (CAs), one for
-controllers and one for switches. If you have an established PKI,
-Open vSwitch can use it directly. Otherwise, refer to "Establishing a
-Public Key Infrastructure" below.
-
-To configure the controller to listen for SSL connections on port 6633
-(the default), invoke it as follows:
-
- # ovs-controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
- --ca-cert=CACERT
-
-where PRIVKEY is a file containing the controller's private key, CERT
-is a file containing the controller CA's certificate for the
-controller's public key, and CACERT is a file containing the root
-certificate for the switch CA. If, for example, your PKI was created
-with the instructions below, then the invocation would look like:
-
- # ovs-controller -v pssl: --private-key=ctl-privkey.pem \
- --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
-
-To configure a switch to connect to a controller running on port 6633
-(the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
-
- # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
- --certificate=CERT --ca-cert=CACERT
-
-where DATAPATH is the datapath to connect to (e.g. dp0 or
-unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
-private key, CERT is a file containing the switch CA's certificate for
-the switch's public key, and CACERT is a file containing the root
-certificate for the controller CA. If, for example, your PKI was
-created with the instructions below, then the invocation would look
-like:
-
- # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
- --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
-
-[*] To be specific, Open vSwitch uses TLS version 1.0 or later (TLSv1), as
- specified by RFC 2246, which is very similar to SSL version 3.0.
- TLSv1 was released in January 1999, so all current software and
- hardware should implement it.
-
-Establishing a Public Key Infrastructure
-----------------------------------------
-
-If you do not have a PKI, the ovs-pki script included with Open vSwitch
-can help. To create an initial PKI structure, invoke it as:
- % ovs-pki init
-which will create and populate a new PKI directory. The default
-location for the PKI directory depends on how the Open vSwitch tree was
-configured (to see the configured default, look for the --dir option
-description in the output of "ovs-pki --help").
-
-The pki directory contains two important subdirectories. The
-controllerca subdirectory contains controller certificate authority
-related files, including the following:
-
- - cacert.pem: Root certificate for the controller certificate
- authority. This file must be provided to secchan with the
- --ca-cert option to enable it to authenticate valid controllers.
-
- - private/cakey.pem: Private signing key for the controller
- certificate authority. This file must be kept secret. There is
- no need for switches or controllers to have a copy of it.
-
-The switchca subdirectory contains switch certificate authority
-related files, analogous to those in the controllerca subdirectory:
-
- - cacert.pem: Root certificate for the switch certificate
- authority. This file must be provided to the controller program
- with the --ca-cert option to enable it to authenticate valid
- switches.
-
- - private/cakey.pem: Private signing key for the switch
- certificate authority. This file must be kept secret. There is
- no need for switches or controllers to have a copy of it.
-
-After you create the initial structure, you can create keys and
-certificates for switches and controllers with ovs-pki. To create a
-controller private key and certificate in files named ctl-privkey.pem
-and ctl-cert.pem, for example, you could run:
- % ovs-pki req+sign ctl controller
-ctl-privkey.pem and ctl-cert.pem would need to be copied to the
-controller for its use at runtime (they could then be deleted from
-their original locations). The --private-key and --certificate
-options of ovs-controller, respectively, would point to these files.
-
-Analogously, to create a switch private key and certificate in files
-named sc-privkey.pem and sc-cert.pem, for example, you could run:
- % ovs-pki req+sign sc switch
-sc-privkey.pem and sc-cert.pem would need to be copied to the switch
-for its use at runtime (they could then be deleted from their original
-locations). The --private-key and --certificate options,
-respectively, of secchan would point to these files.
+Upgrading Open vSwitch from one version to the next version with minimum
+disruption of traffic going through the system that is using that Open vSwitch
+needs some considerations:
+
+1. If the upgrade only involves upgrading the userspace utilities and daemons
+of Open vSwitch, make sure that the new userspace version is compatible with
+the previously loaded kernel module.
+
+2. An upgrade of userspace daemons means that they have to be restarted.
+Restarting the daemons means that the Openflow flows in the ovs-vswitchd daemon
+will be lost. One way to restore the flows is to let the controller
+re-populate it. Another way is to save the previous flows using a utility
+like ovs-ofctl and then re-add them after the restart. Restoring the old flows
+is accurate only if the new Open vSwitch interfaces retain the old 'ofport'
+values.
+
+3. When the new userspace daemons get restarted, they automatically flush
+the old flows setup in the kernel. This can be expensive if there are hundreds
+of new flows that are entering the kernel but userspace daemons are busy
+setting up new userspace flows from either the controller or an utility like
+ovs-ofctl. Open vSwitch database provides an option to solve this problem
+through the other_config:flow-restore-wait column of the Open_vSwitch table.
+Refer to the ovs-vswitchd.conf.db(5) manpage for details.
+
+4. If the upgrade also involves upgrading the kernel module, the old kernel
+module needs to be unloaded and the new kernel module should be loaded. This
+means that the kernel network devices belonging to Open vSwitch is recreated
+and the kernel flows are lost. The downtime of the traffic can be reduced
+if the userspace daemons are restarted immediately and the userspace flows
+are restored as soon as possible.
+
+The ovs-ctl utility's "restart" function only restarts the userspace daemons,
+makes sure that the 'ofport' values remain consistent across restarts, restores
+userspace flows using the ovs-ofctl utility and also uses the
+other_config:flow-restore-wait column to keep the traffic downtime to the
+minimum. The ovs-ctl utility's "force-reload-kmod" function does all of the
+above, but also replaces the old kernel module with the new one. Open vSwitch
+startup scripts for Debian, XenServer and RHEL use ovs-ctl's functions and it
+is recommended that these functions be used for other software platforms too.
+
+Testsuites
+==========
+
+This section describe Open vSwitch's built-in support for various test
+suites. You must configure and build Open vSwitch (steps 1 through 3
+in "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD"
+above) before you run the tests described here. You do not need to
+install Open vSwitch or to build or load the kernel module to run
+these test suites. You do not need supervisor privilege to run these
+test suites.
+
+Self-Tests
+----------
+
+Open vSwitch includes a suite of self-tests. Before you submit patches
+upstream, we advise that you run the tests and ensure that they pass.
+If you add new features to Open vSwitch, then adding tests for those
+features will ensure your features don't break as developers modify
+other areas of Open vSwitch.
+
+Refer to "Testsuites" above for prerequisites.
+
+To run all the unit tests in Open vSwitch, one at a time:
+ make check
+This takes under 5 minutes on a modern desktop system.
+
+To run all the unit tests in Open vSwitch, up to 8 in parallel:
+ make check TESTSUITEFLAGS=-j8
+This takes under a minute on a modern 4-core desktop system.
+
+To see a list of all the available tests, run:
+ make check TESTSUITEFLAGS=--list
+
+To run only a subset of tests, e.g. test 123 and tests 477 through 484:
+ make check TESTSUITEFLAGS='123 477-484'
+(Tests do not have inter-dependencies, so you may run any subset.)
+
+To run tests matching a keyword, e.g. "ovsdb":
+ make check TESTSUITEFLAGS='-k ovsdb'
+
+To see a complete list of test options:
+ make check TESTSUITEFLAGS=--help
+
+The results of a testing run are reported in tests/testsuite.log.
+Please report test failures as bugs and include the testsuite.log in
+your report.
+
+If you have "valgrind" installed, then you can also run the testsuite
+under valgrind by using "make check-valgrind" in place of "make
+check". All the same options are available via TESTSUITEFLAGS. When
+you do this, the "valgrind" results for test <N> are reported in files
+named tests/testsuite.dir/<N>/valgrind.*. You may find that the
+valgrind results are easier to interpret if you put "-q" in
+~/.valgrindrc, since that reduces the amount of output.
+
+Sometimes a few tests may fail on some runs but not others. This is
+usually a bug in the testsuite, not a bug in Open vSwitch itself. If
+you find that a test fails intermittently, please report it, since the
+developers may not have noticed.
+
+OFTest
+------
+
+OFTest is an OpenFlow protocol testing suite. Open vSwitch includes a
+Makefile target to run OFTest 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.
+
+To run OFTest with Open vSwitch, first read and follow the
+instructions under "Testsuites" above. 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.
+
+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'
+
+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.
+
+Ryu
+---
+
+Ryu is an OpenFlow controller written in Python that includes an
+extensive OpenFlow testsuite. Open vSwitch includes a Makefile target
+to run Ryu in "dummy mode". See "OFTest" above for an explanation of
+dummy mode.
+
+To run Ryu tests with Open vSwitch, first read and follow the
+instructions under "Testsuites" above. Second, obtain a copy of Ryu,
+install its prerequisites, and build it. You do not need to install
+Ryu (some of the tests do not get installed, so it does not help).
+
+To run Ryu tests, run the following command from your Open vSwitch
+build directory:
+ make check-ryu RYUDIR=<ryu-source-dir>
+where <ryu-source-dir> is the absolute path to the root of the Ryu
+source distribution. The default <ryu-source-dir> is $srcdir/../ryu
+where $srcdir is your Open vSwitch source directory, so if this
+default is correct then you make simply run "make check-ryu".
+
+Open vSwitch has not been validated against Ryu. Please do report
+test failures that you believe to represent bugs in Open vSwitch.
+Include the precise versions of Open vSwitch and Ryu in your bug
+report, plus any other information needed to reproduce the problem.