diff options
Diffstat (limited to 'INSTALL')
| -rw-r--r-- | INSTALL | 341 |
1 files changed, 341 insertions, 0 deletions
diff --git a/INSTALL b/INSTALL new file mode 100644 index 000000000..671c4a49d --- /dev/null +++ b/INSTALL @@ -0,0 +1,341 @@ + How to Install Open vSwitch on Linux and FreeBSD + ================================================ + +This document describes how to build and install Open vSwitch on a +generic Linux or FreeBSD 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 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. + + - 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. + + - On Linux, the same kernel version configured as part of the build. + + - For optional support of ingress policing on Linux, the "tc" program + from iproute2 (part of all major distributions and available at + http://www.linux-foundation.org/en/Net:Iproute2). + +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 +========================================================= + +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 + + On FreeBSD you may need to use GNU make (gmake) or NetBSD make + (bmake) instead of the native 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 or FreeBSD". + + - 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. + +Bug Reporting +------------- + +Please report problems to bugs@openvswitch.org. |