- How to Install Open vSwitch on Linux and FreeBSD
- ================================================
+ How to Install Open vSwitch on Linux, FreeBSD and NetBSD
+ ========================================================
This document describes how to build and install Open vSwitch on a
-generic Linux or FreeBSD host. For specifics around installation on a
-specific platform, please see one of these files:
+generic Linux, FreeBSD, or NetBSD host. For specifics around installation
+on a specific platform, please see one of these files:
- INSTALL.Debian
- INSTALL.Fedora
- INSTALL.RHEL
- INSTALL.XenServer
+ - INSTALL.NetBSD
+ - INSTALL.DPDK
Build Requirements
------------------
To compile the userspace programs in the Open vSwitch distribution,
you will need the following software:
- - A make program, e.g. GNU make. BSD make should also work.
+ - GNU make.
+
+ - A C compiler, such as:
- - The GNU C compiler. We generally test with version 4.1, 4.2, or
- 4.3.
+ * GCC 4.x.
- - pkg-config. We test with version 0.22.
+ * Clang. Clang 3.4 and later provide useful static semantic
+ analysis and thread-safety checks. For Ubuntu, there are
+ nightly built packages available on clang's website.
- libssl, from OpenSSL, is optional but recommended if you plan to
connect the Open vSwitch to an OpenFlow controller. libssl is
libssl is installed, then Open vSwitch will automatically build
with support for it.
-To compile the kernel module on Linux, you must also install the
-following. If you cannot build or install the kernel module, you may
-use the userspace-only implementation, at a cost in performance. The
-userspace implementation may also lack some features. Refer to
-INSTALL.userspace for more information.
+ - Python 2.x, for x >= 4.
+
+On Linux, you may choose to compile the kernel module that comes with
+the Open vSwitch distribution or to use the kernel module built into
+the Linux kernel (version 3.3 or later). See the FAQ question "What
+features are not available in the Open vSwitch kernel datapath that
+ships as part of the upstream Linux kernel?" for more information on
+this trade-off. You may also use the userspace-only implementation,
+at some cost in features and performance (see INSTALL.userspace for
+details). To compile the kernel module on Linux, you must also
+install the following:
- A supported Linux kernel version. Please refer to README for a
list of supported versions.
NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is
obsolete and not needed.)
- If GRE tunneling is being used it is recommended that the kernel
- be compiled with IPv6 support (CONFIG_IPV6). This allows for
- special handling (such as path MTU discovery) of IPv6 packets.
+ To use GRE tunneling on Linux 2.6.37 or newer, kernel support
+ for GRE must be compiled in or available as a module
+ (CONFIG_NET_IPGRE_DEMUX).
To configure HTB or HFSC quality of service with Open vSwitch,
you must enable the respective configuration options.
- Automake version 1.10 or later.
- - Python 2.x, for x >= 4.
-
-If you modify the ovsdbmonitor tool, then you will also need the
-following:
-
- - pyuic4 from PyQt4 (http://www.riverbankcomputing.co.uk).
+ - libtool version 2.4 or later. (Older versions might work too.)
To run the unit tests, you also need:
- Perl. Version 5.10.1 is known to work. Earlier versions should
also work.
-If you modify the vswitchd database schema, then the E-R diagram in
-the ovs-vswitchd.conf.db(5) manpage will be updated properly only if
-you have the following:
+The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in
+formats other than plain text, only if you have the following:
- "dot" from graphviz (http://www.graphviz.org/).
- GNU make.
+ - clang, version 3.4 or later
+
+Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful.
+
Installation Requirements
-------------------------
On Linux you should ensure that /dev/urandom exists. To support TAP
devices, you must also ensure that /dev/net/tun exists.
-To run the ovsdbmonitor tool, the machine must also have the following
-software:
-
- - Python 2.x, for x >= 4.
-
- - Python Twisted Conch.
-
- - Python JSON.
-
- - PySide or PyQt4.
-
- - Python Zope interface module.
-
-(On Debian "lenny" the above can be installed with "apt-get install
-python-json python-qt4 python-zopeinterface python-twisted-conch".)
-
-Building and Installing Open vSwitch for Linux or FreeBSD
-=========================================================
+Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD
+=================================================================
Once you have installed all the prerequisites listed above in the Base
Prerequisites section, follow the procedure below to build.
% ./configure CC=gcc-4.2
+ To use 'clang' compiler:
+
+ % ./configure CC=clang
+
To build the Linux kernel module, so that you can run the
kernel-based switch, pass the location of the kernel build
directory on --with-linux. For example, to build for a running
% ./configure --with-linux=/lib/modules/`uname -r`/build
+ If --with-linux requests building for an unsupported version of
+ Linux, then "configure" will fail with an error message. Please
+ refer to the FAQ for advice in that case.
+
If you wish to build the kernel module for an architecture other
than the architecture of the machine used for the build, you may
specify the kernel architecture string using the KARCH variable
% ./configure --with-linux=/path/to/linux KARCH=mips
+ If you plan to do much Open vSwitch development, you might want to
+ add --enable-Werror, which adds the -Werror option to the compiler
+ command line, turning warnings into errors. That makes it
+ impossible to miss warnings generated by the build.
+
+ To build with gcov code coverage support, add --enable-coverage,
+ e.g.:
+
+ % ./configure --enable-coverage
+
The configure script accepts a number of other options and honors
additional environment variables. For a full list, invoke
configure with the --help option.
-3. Run make in the top source directory:
+3. Run GNU make in the top source directory, e.g.:
% make
- On FreeBSD you may need to use GNU make (gmake) or NetBSD make
- (bmake) instead of the native make.
+ or if GNU make is installed as "gmake":
+
+ % gmake
For improved warnings if you installed "sparse" (see
- "Prerequisites"), add C=1 to the "make" command line.
+ "Prerequisites"), add C=1 to the command line.
4. Consider running the testsuite. Refer to "Running the Testsuite"
below, for instructions.
6. Run "make install" to install the executables and manpages into the
running system, by default under /usr/local.
-7. If you built kernel modules, you may load them with "insmod", e.g.:
+7. If you built kernel modules, you may install and load them, e.g.:
- % insmod datapath/linux/openvswitch.ko
+ % make modules_install
+ % /sbin/modprobe openvswitch
- You may need to specify a full path to insmod, e.g. /sbin/insmod.
To verify that the modules have been loaded, run "/sbin/lsmod" and
check that openvswitch is listed.
- If the "insmod" operation fails, look at the last few kernel log
+ If the "modprobe" operation fails, look at the last few kernel log
messages (e.g. with "dmesg | tail"):
- The message "openvswitch: exports duplicate symbol
you do not understand what this means or do not know if your driver
will work, do not set this.
- Once you verify that the kernel modules load properly, you should
- install them:
-
- % make modules_install
-
8. Initialize the configuration database using ovsdb-tool, e.g.:
% mkdir -p /usr/local/etc/openvswitch
Before starting ovs-vswitchd itself, you need to start its
configuration database, ovsdb-server. Each machine on which Open
vSwitch is installed should run its own copy of ovsdb-server.
-Configure it to use the database you created during step 7 of
-installation, above, to listen on a Unix domain socket, to connect to
-any managers specified in the database itself, and to use the SSL
+Configure it to use the database you created during installation (as
+explained above), to listen on a Unix domain socket, to connect to any
+managers specified in the database itself, and to use the SSL
configuration in the database:
% ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
- --remote=db:Open_vSwitch,manager_options \
- --private-key=db:SSL,private_key \
- --certificate=db:SSL,certificate \
- --bootstrap-ca-cert=db:SSL,ca_cert \
+ --remote=db:Open_vSwitch,Open_vSwitch,manager_options \
+ --private-key=db:Open_vSwitch,SSL,private_key \
+ --certificate=db:Open_vSwitch,SSL,certificate \
+ --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \
--pidfile --detach
(If you built Open vSwitch without SSL support, then omit
- If there is no important data in your database, then you may
delete the database file and recreate it with ovsdb-tool,
following the instructions under "Building and Installing Open
- vSwitch for Linux or FreeBSD".
+ vSwitch for Linux, FreeBSD or NetBSD".
- If you want to preserve the contents of your database, back it
up first, then use "ovsdb-tool convert" to upgrade it, e.g.:
% ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
4. Start the Open vSwitch daemons as described under "Building and
- Installing Open vSwitch for Linux or FreeBSD" above.
-
-Running the Testsuite
-=====================
-
-Open vSwitch includes a testsuite. Before you submit patches
+ Installing Open vSwitch for Linux, FreeBSD or NetBSD" above.
+
+Hot Upgrading
+=============
+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.
-You must configure and build Open vSwitch (steps 1 through 3 in
-"Building and Installing Open vSwitch for Linux or FreeBSD" above)
-before you run the testsuite. You do not need to install Open vSwitch
-or to build or load the kernel module to run the testsuite. You do
-not need supervisor privilege to run the testsuite.
+Refer to "Testsuites" above for prerequisites.
To run all the unit tests in Open vSwitch, one at a time:
make check
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
+~/.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.
+
Bug Reporting
--------------
+=============
Please report problems to bugs@openvswitch.org.
git://git.onelab.eu / sliver-openvswitch.git / blobdiff