- 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,
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 <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 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 ovs-bugs@openvswitch.org.
+Please report problems to bugs@openvswitch.org.
git://git.onelab.eu / sliver-openvswitch.git / blobdiff