This document describes how to build and install Open vSwitch on a
generic Linux host. If you want to install Open vSwitch on a Citrix
-XenServer version 5.5.0, see INSTALL.XenServer instead.
+XenServer, see INSTALL.XenServer instead.
-This version of Open vSwitch should be built manually with "configure"
-and "make". Debian packaging for Open vSwitch is also included, but
-they have not been recently tested, and so Debian packages are not a
-recommended way to use this version of Open vSwitch.
+This version of Open vSwitch may be built manually with "configure"
+and "make", as described below. You may also build Debian packages by
+running "dpkg-buildpackage".
Build Requirements
------------------
- The GNU C compiler. We generally test with version 4.1, 4.2, or
4.3.
+ - pkg-config. We test with version 0.22.
+
- libssl, from OpenSSL, is optional but recommended if you plan to
connect the Open vSwitch to an OpenFlow controller. libssl is
required to establish confidentiality and authenticity in the
- connections from an Open vSwitch to an OpenFlow controller. To
- enable, configure with --enable-ssl=yes.
+ connections from an Open vSwitch to an OpenFlow controller. If
+ libssl is installed, then Open vSwitch will automatically build
+ with support for it.
-To compile the kernel module (which is required for operation), you
-must also install the following:
+To compile the kernel module, 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.
- A supported Linux kernel version. Please refer to README for a
list of supported versions.
and 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 configure HTB or HFSC quality of service with Open vSwitch,
+ you must enable the respective configuration options.
+
+ To use Open vSwitch support for TAP devices, you must enable
+ CONFIG_TUN.
+
- To build a kernel module, you need the same version of GCC that
was used to build that kernel.
infrastructure.
If you are working from a Git tree or snapshot (instead of from a
-distribution tarball), or if you modify the Open vSwitch build system,
-you will also need the following software:
+distribution tarball), or if you modify the Open vSwitch build system
+or the database schema, you will also need the following software:
- - Autoconf version 2.63 or later.
+ - Autoconf version 2.64 or later.
- Automake version 1.10 or later.
- - pkg-config. We test with version 0.22.
+ - 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).
+
+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:
+
+ - "dot" from graphviz (http://www.graphviz.org/).
+
+ - Perl. Version 5.10.1 is known to work. Earlier versions should
+ also work.
+
+ - Python 2.x, for x >= 4.
Installation Requirements
-------------------------
if it is installed in a different location, then some Open
vSwitch log messages will not be as detailed.
+You should ensure that /dev/urandom exists. To support TAP devices,
+you must also ensure that /dev/net/tun exists.
+
+To run the ovsdmonitor 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
==============================================
To verify that the modules have been loaded, run "/sbin/lsmod" and
check that openvswitch_mod is listed.
-Configuration
-=============
+ If the "insmod" operation fails, look at the last few kernel log
+ messages (e.g. with "dmesg | tail"):
+
+ - The message "openvswitch_mod: exports duplicate symbol
+ br_should_route_hook (owned by bridge)" means that the bridge
+ module is loaded. Run "/sbin/rmmod bridge" to remove it.
+
+ If "/sbin/rmmod bridge" fails with "ERROR: Module bridge does
+ not exist in /proc/modules", then the bridge is compiled into
+ the kernel, rather than as a module. Open vSwitch does not
+ support this configuration (see "Build Requirements", above).
+
+ - The message "openvswitch_mod: exports duplicate symbol
+ dp_ioctl_hook (owned by ofdatapath)" means that the ofdatapath
+ module from the OpenFlow reference implementation is loaded.
+ Run "/sbin/rmmod ofdatapath" to remove it. (You might have to
+ delete any existing datapaths beforehand, using the "dpctl"
+ program included with the OpenFlow reference implementation.
+ "ovs-dpctl" will not work.)
+
+ - Otherwise, the most likely problem is that Open vSwitch was
+ built for a kernel different from the one into which you are
+ trying to load it. Run "modinfo" on openvswitch_mod.ko and on
+ a module built for the running kernel, e.g.:
+
+ % /sbin/modinfo openvswitch_mod.ko
+ % /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko
+
+ Compare the "vermagic" lines output by the two commands. If
+ they differ, then Open vSwitch was built for the wrong kernel.
+
+ - If you decide to report a bug or ask a question related to
+ module loading, please include the output from the "dmesg" and
+ "modinfo" commands mentioned above.
+
+ There is an optional module parameter to openvswitch_mod.ko called
+ vlan_tso that enables TCP segmentation offload over VLANs on NICs
+ that support it. Many drivers do not expose support for TSO on VLANs
+ in a way that Open vSwitch can use but there is no way to detect
+ whether this is the case. If you know that your particular driver can
+ handle it (for example by testing sending large TCP packets over VLANs)
+ then passing in a value of 1 may improve performance. Modules built for
+ Linux kernels 2.6.37 and later, as well as specially patched versions
+ of earlier kernels, do not need this and do not have this parameter. If
+ you do not understand what this means or do not know if your driver
+ will work, do not set this.
+
+7. Initialize the configuration database using ovsdb-tool, e.g.:
+
+ % mkdir -p /usr/local/etc/openvswitch
+ % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
+
+Startup
+=======
+
+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
+configuration in the database:
+
+ % ovsdb-server /usr/local/etc/openvswitch/conf.db \
+ --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 \
+ --pidfile --detach
+
+(If you built Open vSwitch without SSL support, then omit
+--private-key, --certificate, and --bootstrap-ca-cert.)
+
+Then initialize the database using ovs-vsctl. This is only
+necessary the first time after you create the database with
+ovsdb-tool (but running it at any time is harmless):
+
+ % ovs-vsctl --no-wait init
+
+Then start the main Open vSwitch daemon, telling it to connect to the
+same Unix domain socket:
+
+ % ovs-vswitchd unix:/usr/local/var/run/openvswitch/db.sock \
+ --pidfile --detach
+
+Now you may use ovs-vsctl to set up bridges and other Open vSwitch
+features. For example, to create a bridge named br0 and add ports
+eth0 and vif1.0 to it:
+
+ % ovs-vsctl add-br br0
+ % ovs-vsctl add-port br0 eth0
+ % ovs-vsctl add-port br0 vif1.0
+
+Please refer to ovs-vsctl(8) for more details.
+
+Upgrading
+=========
+
+When you upgrade Open vSwitch from one version to another, you should
+also upgrade the database schema:
+
+1. Stop the Open vSwitch daemons, e.g.:
+
+ % kill `cd /usr/local/var/run && cat ovsdb-server.pid ovs-vswitchd.pid`
+
+2. Install the new Open vSwitch release.
+
+3. Upgrade the database, in one of the following two ways:
-Open vSwitch is configured primarily through a configuration file,
-whose name is specified on the ovs-vswitchd command line. Please
-refer to ovs-vswitchd(8) and ovs-vswitchd.conf(5) for information on
-how to start ovs-vswitchd and the syntax of its configuration file,
-respectively.
+ - 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".
-At runtime, you may make ovs-vswitchd reload its configuration file
-and update its configuration accordingly by sending it a SIGHUP
-signal. The ovs-appctl utility can also be used to do this:
+ - If you want to preserve the contents of your database, back it
+ up first, then use "ovsdb-tool convert" to upgrade it, e.g.:
- % ovs-appctl vswitchd/reload
+ % ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema
-In the latter case, ovs-appctl will wait for ovs-vswitchd to finish
-reloading before it exits.
+4. Start the Open vSwitch daemons as described under "Building and
+ Installing Open vSwitch for Linux" above.
Bug Reporting
-------------
git://git.onelab.eu / sliver-openvswitch.git / blobdiff