+++ /dev/null
- How to Install Open vSwitch on Linux
- ====================================
-
-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, see INSTALL.XenServer instead.
-
-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
-------------------
-
-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.
-
- - 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. If
- libssl is installed, then Open vSwitch will automatically build
- with support for it.
-
-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.
-
- The Open vSwitch datapath requires bridging support
- (CONFIG_BRIDGE) to be built as a kernel module. (This is common
- in kernels provided by Linux distributions.) The bridge module
- must not be loaded or in use. If the bridge module is running
- (check with "lsmod | grep bridge"), you must remove it ("rmmod
- bridge") before starting the datapath.
-
- For optional support of ingress policing, you must enable kernel
- configuration options NET_CLS_BASIC, NET_SCH_INGRESS, 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.
-
- - A kernel build directory corresponding to the Linux kernel image
- the module is to run on. Under Debian and Ubuntu, for example,
- each linux-image package containing a kernel binary has a
- corresponding linux-headers package with the required build
- 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
-or the database schema, you will also need the following software:
-
- - Autoconf version 2.64 or later.
-
- - 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).
-
-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.
-
-If you are going to extensively modify Open vSwitch, please consider
-installing the following to obtain better warnings:
-
- - "sparse" version 0.4.4 or later
- (http://www.kernel.org/pub/software/devel/sparse/dist/).
-
- - GNU make.
-
-Installation Requirements
--------------------------
-
-The machine on which Open vSwitch is to be installed must have the
-following software:
-
- - libc compatible with the libc used for build.
-
- - libssl compatible with the libssl used for build, if OpenSSL was
- used for the build.
-
- - The Linux kernel version configured as part of the build.
-
- - For optional support of ingress policing, the "tc" program from
- iproute2 (part of all major distributions and available at
- http://www.linux-foundation.org/en/Net:Iproute2).
-
-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
-==============================================
-
-Once you have installed all the prerequisites listed above in the Base
-Prerequisites section, follow the procedure below to build.
-
-1. If you pulled the sources directly from an Open vSwitch Git tree,
- run boot.sh in the top source directory:
-
- % ./boot.sh
-
-2. In the top source directory, configure the package by running the
- configure script. You can usually invoke configure without any
- arguments:
-
- % ./configure
-
- By default all files are installed under /usr/local. If you want
- to install into, e.g., /usr and /var instead of /usr/local and
- /usr/local/var, add options as shown here:
-
- % ./configure --prefix=/usr --localstatedir=/var
-
- To use a specific C compiler for compiling Open vSwitch user
- programs, also specify it on the configure command line, like so:
-
- % ./configure CC=gcc-4.2
-
- 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
- instance of Linux:
-
- % ./configure --with-linux=/lib/modules/`uname -r`/build
-
- 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
- when invoking the configure script. For example, to build for MIPS
- with Linux:
-
- % ./configure --with-linux=/path/to/linux KARCH=mips
-
- 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:
-
- % make
-
- For improved warnings if you installed "sparse" (see
- "Prerequisites"), add C=1 to the "make" command line.
-
-4. Become root by running "su" or another program.
-
-5. Run "make install" to install the executables and manpages into the
- running system, by default under /usr/local.
-
-6. If you built kernel modules, you may load them with "insmod", e.g.:
-
- % insmod datapath/linux/openvswitch.ko
-
- 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
- messages (e.g. with "dmesg | tail"):
-
- - The message "openvswitch: 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: 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.ko and on
- a module built for the running kernel, e.g.:
-
- % /sbin/modinfo openvswitch.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.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 --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 --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/openvswitch && 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:
-
- - 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".
-
- - 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" above.
-
-Bug Reporting
--------------
-
-Please report problems to bugs@openvswitch.org.
git://git.onelab.eu / sliver-openvswitch.git / blobdiff