- [INSTALL.RHEL.md]
- [INSTALL.XenServer.md]
- [INSTALL.NetBSD.md]
+ - [INSTALL.Windows.md]
- [INSTALL.DPDK.md]
Build Requirements
analysis and thread-safety checks. For Ubuntu, there are
nightly built packages available on clang's website.
+ * MSVC 2013. See [INSTALL.Windows] for additional Windows build
+ instructions.
+
While OVS may be compatible with other compilers, optimal
support for atomic operations may be missing, making OVS very
slow (see lib/ovs-atomic.h).
libssl is installed, then Open vSwitch will automatically build
with support for it.
- - Python 2.x, for x >= 4.
+ - libcap-ng, written by Steve Grubb, is optional but recommended. It
+ is required to run OVS daemons as a non-root user with dropped root
+ privileges. If libcap-ng is installed, then Open vSwitch will
+ automatically build with support for it.
+
+ - Python 2.7. You must also have the Python six library.
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
- 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:
- clang, version 3.4 or later
+ - flake8 (for Python code)
+
Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful.
Installation Requirements
from iproute2 (part of all major distributions and available at
http://www.linux-foundation.org/en/Net:Iproute2).
+ - Python 2.7. You must also have the Python six library.
+
On Linux you should ensure that /dev/urandom exists. To support TAP
devices, you must also ensure that /dev/net/tun exists.
Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD
=================================================================
-Once you have installed all the prerequisites listed above in the Base
-Prerequisites section, follow the procedure below to build.
+Once you have installed all the prerequisites listed above in the
+Base Prerequisites section, follow the procedures below to bootstrap,
+to configure and to build the code.
+
+Bootstrapping the Sources
+-------------------------
-1. If you pulled the sources directly from an Open vSwitch Git tree,
- run boot.sh in the top source directory:
+This step is not needed if you have downloaded a released tarball.
+If you pulled the sources directly from an Open vSwitch Git tree or
+got a Git tree snapshot, then run boot.sh in the top source directory
+to build the "configure" script.
`% ./boot.sh`
-2. Configure the package by running the configure script. You can
- usually invoke configure without any arguments. For example:
+
+Configuring the Sources
+-----------------------
+
+Configure the package by running the configure script. You can
+usually invoke configure without any arguments. For example:
`% ./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:
+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`
- By default, static libraries are built and linked against. If you
- want to use shared libraries instead:
+By default, static libraries are built and linked against. If you
+want to use shared libraries instead:
- % ./configure --enable-shared
+ `% ./configure --enable-shared`
- To use a specific C compiler for compiling Open vSwitch user
- programs, also specify it on the configure command line, like so:
+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 use 'clang' compiler:
+To use 'clang' compiler:
`% ./configure CC=clang`
- 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:
+To supply special flags to the C compiler, specify them as CFLAGS on
+the configure command line. If you want the default CFLAGS, which
+include "-g" to build debug symbols and "-O2" to enable optimizations,
+you must include them yourself. For example, to build with the
+default CFLAGS plus "-mssse3", you might run configure as follows:
+
+ `% ./configure CFLAGS="-g -O2 -mssse3"`
+
+Note that these CFLAGS are not applied when building the Linux
+kernel module. Custom CFLAGS for the kernel module are supplied
+using the EXTRA_CFLAGS variable when running make. So, for example:
+
+ `% make EXTRA_CFLAGS="-Wno-error=date-time"`
+
+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 --with-linux requests building for an unsupported version of
- Linux, then "configure" will fail with an error message. Please
- refer to the [FAQ.md] for advice in that case.
+If --with-linux requests building for an unsupported version of
+Linux, then "configure" will fail with an error message. Please
+refer to the [FAQ.md] for advice in that case.
- 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:
+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`
- 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.
+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.
- To build with gcov code coverage support, add --enable-coverage,
- e.g.:
+To build with gcov code coverage support, add --enable-coverage,
+e.g.:
`% ./configure --enable-coverage`
- The configure script accepts a number of other options and honors
- additional environment variables. For a full list, invoke
- configure with the --help option.
+The configure script accepts a number of other options and honors
+additional environment variables. For a full list, invoke
+configure with the --help option.
- You can also run configure from a separate build directory. This
- is helpful if you want to build Open vSwitch in more than one way
- from a single source directory, e.g. to try out both GCC and Clang
- builds, or to build kernel modules for more than one Linux version.
- Here is an example:
+You can also run configure from a separate build directory. This
+is helpful if you want to build Open vSwitch in more than one way
+from a single source directory, e.g. to try out both GCC and Clang
+builds, or to build kernel modules for more than one Linux version.
+Here is an example:
- `% mkdir _gcc && (cd _gcc && ../configure CC=gcc)`
+ `% mkdir _gcc && (cd _gcc && ../configure CC=gcc)`
`% mkdir _clang && (cd _clang && ../configure CC=clang)`
-3. Run GNU make in the build directory, e.g.:
+
+Building the Sources
+--------------------
+
+1. Run GNU make in the build directory, e.g.:
`% make`
If you used a separate build directory, run make or gmake from that
directory, e.g.:
- `% make -C _gcc`
+ `% make -C _gcc`
`% make -C _clang`
- For improved warnings if you installed "sparse" (see
- "Prerequisites"), add C=1 to the command line.
+ For improved warnings if you installed "sparse" (see "Prerequisites"),
+ add C=1 to the command line.
-4. Consider running the testsuite. Refer to "Running the Testsuite"
+ Some versions of Clang and ccache are not completely compatible.
+ If you see unusual warnings when you use both together, consider
+ disabling ccache for use with Clang.
+
+2. Consider running the testsuite. Refer to "Running the Testsuite"
below, for instructions.
-5. Become root by running "su" or another program.
+3. Become root by running "su" or another program.
-6. Run "make install" to install the executables and manpages into the
+4. Run "make install" to install the executables and manpages into the
running system, by default under /usr/local.
-7. If you built kernel modules, you may install and load them, e.g.:
+5. If you built kernel modules, you may install and load them, e.g.:
- `% make modules_install`
+ `% make modules_install`
`% /sbin/modprobe openvswitch`
To verify that the modules have been loaded, run "/sbin/lsmod" and
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.
-
-8. Initialize the configuration database using ovsdb-tool, e.g.:
-
- `% mkdir -p /usr/local/etc/openvswitch`
+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.
+
+6. 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
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,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
+ ```
(If you built Open vSwitch without SSL support, then omit
--private-key, --certificate, and --bootstrap-ca-cert.)
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
+ `% 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
+ `% 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
+ `% 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.
==========
This section describe Open vSwitch's built-in support for various test
-suites. You must configure and build Open vSwitch (steps 1 through 3
+suites. You must bootstrap, configure and build Open vSwitch (steps are
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
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.
+developers may not have noticed. You can make the testsuite
+automatically rerun tests that fail, by adding RECHECK=yes to the
+"make" command line, e.g.:
+ `make check TESTSUITEFLAGS=-j8 RECHECK=yes`
OFTest
------
Vagrant
-------
-Requires: Vagrant and a compatible hypervisor
+Requires: Vagrant (version 1.7.0 or later) and a compatible hypervisor
+
+You must bootstrap and configure the sources (steps are in "Building
+and Installing Open vSwitch for Linux, FreeBSD or NetBSD" above) before
+you run the steps described here.
A Vagrantfile is provided allowing to compile and provision the source
tree as found locally in a virtual machine using the following commands:
vagrant ssh
This will bring up w Fedora 20 VM by default, alternatively the
-`Vagrantfile.in` can be modified to use a different distribution box as
-base. Also, the VM can be reprovisioned at any time to recompile and
-reinstall OVS:
+`Vagrantfile` can be modified to use a different distribution box as
+base. Also, the VM can be reprovisioned at any time:
vagrant provision
+OVS out-of-tree compilation environment can be set up with:
+
+ ./boot.sh
+ vagrant provision --provision-with configure_ovs,build_ovs
+
+This will set up an out-of-tree build environment in /home/vagrant/build.
+The source code can be found in /vagrant. Out-of-tree build is preferred
+to work around limitations of the sync file systems.
+
+To recompile and reinstall OVS using RPM:
+
+ ./boot.sh
+ vagrant provision --provision-with configure_ovs,install_rpm
+
+Two provisioners are included to run system tests with the OVS kernel
+module or with a userspace datapath. This tests are different from
+the self-tests mentioned above. To run them:
+
+ ./boot.sh
+ vagrant provision --provision-with configure_ovs,test_ovs_kmod,test_ovs_system_userspace
+
Continuous Integration with Travis-CI
-------------------------------------
projects / cascardo / ovs.git / blobdiff