X-Git-Url: http://git.onelab.eu/?p=sliver-openvswitch.git;a=blobdiff_plain;f=INSTALL;h=afefb518196162b4bf3abb3a841ca4ad9a4dfdb8;hp=994e8d320f4d255abbd1474147dba56039278e8f;hb=HEAD;hpb=064af42167bf4fc9aaea2702d80ce08074b889c0 diff --git a/INSTALL b/INSTALL index 994e8d320..afefb5181 100644 --- a/INSTALL +++ b/INSTALL @@ -1,74 +1,79 @@ - Open vSwitch Installation Instructions + How to Install Open vSwitch on Linux, FreeBSD and NetBSD + ======================================================== -This document describes how to build, install, and execute -Open vSwitch. +This document describes how to build and install Open vSwitch on a +generic Linux, FreeBSD, or NetBSD host. For specifics around installation +on a specific platform, please see one of these files: -Open vSwitch implements an Ethernet switch with MAC learning that may -be configured with any of the following features: + - INSTALL.Debian + - INSTALL.Fedora + - INSTALL.RHEL + - INSTALL.XenServer + - INSTALL.NetBSD + - INSTALL.DPDK - * NIC bonding with automatic fail-over and source MAC-based TX - load balancing ("SLB"). - - * 802.1Q VLAN support. - - * Port mirroring, with optional VLAN tagging. - - * NetFlow v5 flow logging. - - * Connectivity to an external OpenFlow controller, such as - NOX. +Build Requirements +------------------ -The current version of this distribution requires a kernel module to -be built and loaded. An (optional) entirely userspace switch is on -the roadmap for future versions. +To compile the userspace programs in the Open vSwitch distribution, +you will need the following software: -The distribution also contains a number of related utilities. + - GNU make. -Build Methods -============= + - A C compiler, such as: -There are two principal ways to build and install this distribution: + * GCC 4.x. - - Using "configure" and "make" in the ordinary way. See - Building Conventionally below for detailed instructions. + * 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. - - As a set of Debian packages. Refer to Building Debian - Packages, below, for instructions. + - 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. -Base Prerequisites ------------------- + - Python 2.x, for x >= 4. -Regardless of how it is built, Open vSwitch has a common set of -prerequisites. To compile the userspace programs in the OpenFlow -reference distribution, you will need the following software: +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 make program, e.g. GNU make - (http://www.gnu.org/software/make/). BSD make should also work. + - A supported Linux kernel version. Please refer to README for a + list of supported versions. - - The GNU C compiler (http://gcc.gnu.org/). We generally test - with version 4.2 or 4.3. + 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. - - libssl, from OpenSSL (http://www.openssl.org/), 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. + 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.) -To compile the kernel module, you must also install the following: + 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). - - A supported Linux kernel version. Please refer to README for a - list of supported versions. + To configure HTB or HFSC quality of service with Open vSwitch, + you must enable the respective configuration options. - The OpenFlow 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. + 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 (usually version 4.0 or later). + 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, @@ -77,438 +82,458 @@ To compile the kernel module, you must also install the following: 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: - - - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf). - - - Automake version 1.10 or later (http://www.gnu.org/software/automake). - - - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test - with version 0.22. - -Debian Prerequisites --------------------- +distribution tarball), or if you modify the Open vSwitch build system +or the database schema, you will also need the following software: -To build Debian packages from the Open vSwitch distribution, you will -need to install a number of Debian packages in addition to the base -prerequisites listed above. These additional prerequisites may be -found listed as "Build-Depends" in debian/control in the source tree. -To check that they are installed, first install the dpkg-dev package, -then run dpkg-checkbuilddeps from the top level of the OpenFlow source -tree. + - Autoconf version 2.64 or later. -To build Debian packages without being root, also install the -"fakeroot" package. + - Automake version 1.10 or later. -Building Conventionally -======================= + - libtool version 2.4 or later. (Older versions might work too.) -This section explains how to build and install the Open vSwitch -distribution in the ordinary way using "configure" and "make". +To run the unit tests, you also need: -0. Check that you have installed all the prerequisites listed above in - the Base Prerequisites section. + - Perl. Version 5.10.1 is known to work. Earlier versions should + also work. -1. In the top source directory, configure the package by running the - configure script. You can usually invoke configure without any - arguments: +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: - % ./configure + - "dot" from graphviz (http://www.graphviz.org/). - To use a specific C compiler for compiling OpenFlow user programs, - also specify it on the configure command line, like so: + - Perl. Version 5.10.1 is known to work. Earlier versions should + also work. - % ./configure CC=gcc-4.2 + - Python 2.x, for x >= 4. - 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-l26. For example, to build for a running - instance of Linux 2.6: +If you are going to extensively modify Open vSwitch, please consider +installing the following to obtain better warnings: - % ./configure --with-l26=/lib/modules/`uname -r`/build + - "sparse" version 0.4.4 or later + (http://www.kernel.org/pub/software/devel/sparse/dist/). - 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 2.6: + - GNU make. - % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips + - clang, version 3.4 or later - The configure script accepts a number of other options and honors - additional environment variables. For a full list, invoke - configure with the --help option. - -2. Run make in the top source directory: +Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful. - % make - - The following main binaries will be built: - - - Virtual switch daemon: vswitchd/ovs-vswitchd - - - Bridge compatibility daemon: vswitchd/ovs-brcompatd - - - Datapath administration utility: utilities/ovs-dpctl. - - Some less important binaries will be built also: - - - Runtime configuration utility: utilities/ovs-appctl. - - - Simple OpenFlow controller: utilities/ovs-controller. - - - Secure channel executable: secchan/secchan. +Installation Requirements +------------------------- - - Miscellaneous utilities: utilities/ovs-discover, - utilities/ovs-kill. +The machine on which Open vSwitch is to be installed must have the +following software: - - ANSI terminal support for EZIO 16x2 LCD panel: - extras/ezio/ezio-term (only if the proper libraries are - installed). + - libc compatible with the libc used for build. - - Switch monitoring UI for small text displays: - extras/ezio/ovs-switchui (only if the proper libraries are - installed). + - libssl compatible with the libssl used for build, if OpenSSL was + used for the build. - - Tests: various binaries in tests/. + - On Linux, the same kernel version configured as part of the build. - If you passed --with-l26 to configure, "make" will also build the - following kernel modules: + - 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). - - datapath/linux-2.6/brcompat_mod.ko +On Linux you should ensure that /dev/urandom exists. To support TAP +devices, you must also ensure that /dev/net/tun exists. - - datapath/linux-2.6/openflow_mod.ko +Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD +================================================================= -3. Run "make install" to install the executables and manpages into the - running system, by default under /usr/local. +Once you have installed all the prerequisites listed above in the Base +Prerequisites section, follow the procedure below to build. -4. If you built kernel modules, you may load them with "insmod", e.g.: +1. If you pulled the sources directly from an Open vSwitch Git tree, + run boot.sh in the top source directory: - % insmod datapath/linux-2.6/openflow_mod.ko + % ./boot.sh - The insmod program must be run as root. 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 openflow_mod is - listed. +2. In the top source directory, configure the package by running the + configure script. You can usually invoke configure without any + arguments: -5. Test the virtuaal switch, as described under Testing the Virtual -Switch below. + % ./configure -Building Debian Packages -======================== + 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: -Follow these instructions to build Debian packages for OpenFlow. + % ./configure --prefix=/usr --localstatedir=/var -0. Check that you have installed all the prerequisites listed above in - the Base Prerequisites and Debian Prerequisites sections above. + To use a specific C compiler for compiling Open vSwitch user + programs, also specify it on the configure command line, like so: -1. In the top source directory, run the following command, as root: + % ./configure CC=gcc-4.2 - % dpkg-buildpackage + To use 'clang' compiler: - Alternatively, if you installed the "fakeroot" package, you may run - dpkg-buildpackage as an ordinary user with the following syntax: + % ./configure CC=clang - % dpkg-buildpackage -rfakeroot + 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: - The following packages will be built in the directory above the - source tree: + % ./configure --with-linux=/lib/modules/`uname -r`/build - - openflow-controller: The OpenFlow controller. Depends on - openflow-pki (see below). + 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. - - openflow-switch: Install this package on a machine that acts - as an OpenFlow kernel switch. + 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: - - openflow-datapath-source: Source code for OpenFlow's Linux - kernel module. + % ./configure --with-linux=/path/to/linux KARCH=mips - - openflow-pki: Public-key infrastructure for OpenFlow. Install - this package on a machine that acts as an OpenFlow PKI server - (see "Establishing a Public Key Infrastructure" below). + 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. - - openflow-common: Files and utilities required by more than one - of the above packages. + To build with gcov code coverage support, add --enable-coverage, + e.g.: -2. To set up an OpenFlow controller, install the openflow-controller - package and its dependencies. You may configure it by editing - /etc/default/openflow-controller, e.g. to enable non-SSL - connections, which are disabled by default. If you change the - default settings, you will need to restart the controller by - running: + % ./configure --enable-coverage - % /etc/init.d/openflow-controller restart + 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. To set up an OpenFlow switch, install the openflow-switch package - and its dependencies. If it is to be a kernel-based switch, also - install openflow-datapath-source, then follow the instructions in - /usr/share/doc/openflow-datapath-source/README.Debian to build and - install the kernel module. +3. Run GNU make in the top source directory, e.g.: - You may configure the switch one of the following ways: + % make - - Completely by hand, as described under the Testing section - below. + or if GNU make is installed as "gmake": - For the userspace datapath-based switch, this is the only - supported form of configuration. + % gmake - - By editing /etc/default/openflow-switch. You must at least - configure some network devices, by uncommenting NETDEVS and - adding the appropriate devices to the list, e.g. NETDEVS="eth0 - eth1". + For improved warnings if you installed "sparse" (see + "Prerequisites"), add C=1 to the command line. - After you edit this file, you will need to start the switch by - running: +4. Consider running the testsuite. Refer to "Running the Testsuite" + below, for instructions. - % /etc/init.d/openflow-switch restart +5. Become root by running "su" or another program. - This form of configuration is not supported for the userspace - datapath-based switch. +6. Run "make install" to install the executables and manpages into the + running system, by default under /usr/local. - - By running the ovs-switch-setup program. This interactive - program will walk you through all the steps of configuring an - OpenFlow switch, including configuration of SSL certificates. - Run it without arguments, as root: +7. If you built kernel modules, you may install and load them, e.g.: - % ovs-switch-setup + % make modules_install + % /sbin/modprobe openvswitch - This form of configuration is not supported for the userspace - datapath-based switch. + To verify that the modules have been loaded, run "/sbin/lsmod" and + check that openvswitch is listed. -Installation -============ + If the "modprobe" operation fails, look at the last few kernel log + messages (e.g. with "dmesg | tail"): -This section explains how to install Open vSwitch in a network with one -controller and one or more switches, each of which runs on a separate -machine. Before you begin, you must decide on one of two ways for -each switch to reach the controller over the network: + - 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. - - Use a "control network" that is completely separate from the - "data network" to be controlled ("out-of-band control"). The - location of the controller must be configured manually in this - case. + 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). - - Use the same network for control and for data ("in-band - control"). When in-band control is used, the location of the - controller may be configured manually or discovered - automatically. We will assume manual configuration here; - please refer to secchan(8) for instructions on setting up - controller discovery. + - 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.) -Controller Setup ----------------- + - 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.: -On the machine that is to be the OpenFlow controller, start the -"ovs-controller" program listening for connections from switches on -TCP port 6633 (the default), as shown below. + % /sbin/modinfo openvswitch.ko + % /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko - # ovs-controller -v ptcp: + Compare the "vermagic" lines output by the two commands. If + they differ, then Open vSwitch was built for the wrong kernel. -(See ovs-controller(8) for more details) + - 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. -Make sure the machine hosting the controller is reachable by the -switch. + 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. -Testing the Virtual Switch --------------------------- +8. Initialize the configuration database using ovsdb-tool, e.g.: -The Open vSwitch kernel module must be loaded, as described under -"Building Conventionally", before it may be used. + % mkdir -p /usr/local/etc/openvswitch + % ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema -0. The commands below must run as root, so log in as root, or use a - program such as "su" to become root temporarily. +Startup +======= -1. Create a datapath instance. The command below creates a datapath - identified as dp0 (see ovs-dpctl(8) for more detailed usage - information). +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 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: - # ovs-dpctl add-dp dp0 - - (dp0 is the first datapath within a host. openvswitch_mod supports - multiple datapaths within the same host, which would be identified - as dp1, dp2, etc.) + % ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \ + --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 - Creating datapath dp0 creates a new network device, also named dp0. - This network device, called the datapath's "local port", will be - bridged to the physical switch ports by the secchan, for use in - in-band control. +(If you built Open vSwitch without SSL support, then omit +--private-key, --certificate, and --bootstrap-ca-cert.) -2. Use ovs-dpctl to attach the datapath to physical interfaces on the - machine. Say, for example, you want to create a trivial 2-port - switch using interfaces eth1 and eth2, you would issue the - following commands: +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-dpctl add-if dp0 eth1 - # ovs-dpctl add-if dp0 eth2 + % ovs-vsctl --no-wait init - You can verify that the interfaces were successfully added by asking - ovs-dpctl to print the current status of datapath dp0: +Then start the main Open vSwitch daemon, telling it to connect to the +same Unix domain socket: - # ovs-dpctl show dp0 + % ovs-vswitchd --pidfile --detach -3. Arrange so that the switch can reach the controller over the - network. +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: - - If you are using out-of-band control, at this point make sure - that the switch machine can reach the controller over the - network. + % ovs-vsctl add-br br0 + % ovs-vsctl add-port br0 eth0 + % ovs-vsctl add-port br0 vif1.0 - - If you are using in-band control, then at this point you must - configure the dp0 network device created in step 1. This - device is not yet bridged to any physical network (because - secchan does that, and it is not yet running), so the next - step depends on whether connectivity is required to configure - the device's IP address: +Please refer to ovs-vsctl(8) for more details. - * If the switch has a static IP address, you may configure - its IP address now, e.g.: +Upgrading +========= - # ifconfig dp0 192.168.1.1 +When you upgrade Open vSwitch from one version to another, you should +also upgrade the database schema: - * If the switch does not have a static IP address, e.g. its - IP address is obtained dynamically via DHCP, then proceed - to step 4. The DHCP client will not be able to contact - the DHCP server until the secure channel has started up. +1. Stop the Open vSwitch daemons, e.g.: - - If you are using in-band control with controller discovery, no - configuration is required at this point. You may proceed to - step 4. + % kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid` -4. Run secchan to start the secure channel connecting the datapath to - a remote controller. If the controller is running on host - 192.168.1.2 port 6633 (the default port), the secchan invocation - would look like this: +2. Install the new Open vSwitch release. - # secchan dp0 tcp:192.168.1.2 +3. Upgrade the database, in one of the following two ways: - - If you are using in-band control with controller discovery, omit - the second argument to the secchan command. + - 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, FreeBSD or NetBSD". - - If you are using out-of-band control, add --out-of-band to the - command line. + - If you want to preserve the contents of your database, back it + up first, then use "ovsdb-tool convert" to upgrade it, e.g.: -5. If you are using in-band control with manual configuration, and the - switch obtains its IP address dynamically, then you may now obtain - the switch's IP address, e.g. by invoking a DHCP client. The - secure channel will only be able to connect to the controller after - an IP address has been obtained. + % ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema -6. The secure channel should connect to the controller within a few - seconds. It may take a little longer if controller discovery is in - use, because the switch must then also obtain its own IP address - and the controller's location via DHCP. +4. Start the Open vSwitch daemons as described under "Building and + Installing Open vSwitch for Linux, FreeBSD or NetBSD" above. -Configuration +Hot Upgrading ============= - -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 are reported in files +named tests/testsuite.dir//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= +where 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= 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= 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= +where is the absolute path to the root of the Ryu +source distribution. The default 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 ovs-bugs@openvswitch.org. +Please report problems to bugs@openvswitch.org.