2 Licensed under the Apache License, Version 2.0 (the "License"); you may
3 not use this file except in compliance with the License. You may obtain
4 a copy of the License at
6 http://www.apache.org/licenses/LICENSE-2.0
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10 WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11 License for the specific language governing permissions and limitations
14 Convention for heading levels in Open vSwitch documentation:
16 ======= Heading 0 (reserved for the title in a document)
22 Avoid deeper levels because they do not render well.
24 =========================================
25 Open vSwitch on Linux, FreeBSD and NetBSD
26 =========================================
28 This document describes how to build and install Open vSwitch on a generic
29 Linux, FreeBSD, or NetBSD host. For specifics around installation on a specific
30 platform, refer to one of the other installation guides listed in :doc:`index`.
32 Obtaining Open vSwitch Sources
33 ------------------------------
35 The canonical location for Open vSwitch source code is its Git
36 repository, which you can clone into a directory named "ovs" with::
38 $ git clone https://github.com/openvswitch/ovs.git
40 Cloning the repository leaves the "master" branch initially checked
41 out. This is the right branch for general development. If, on the
42 other hand, if you want to build a particular released version, you
43 can check it out by running a command such as the following from the
48 The repository also has a branch for each release series. For
49 example, to obtain the latest fixes in the Open vSwitch 2.7.x release
50 series, which might include bug fixes that have not yet been in any
51 released version, you can check it out from the "ovs" directory with::
53 $ git checkout origin/branch-2.7
55 If you do not want to use Git, you can also obtain tarballs for Open
56 vSwitch release versions via http://openvswitch.org/download/, or
57 download a ZIP file for any snapshot from the web interface at
58 https://github.com/openvswitch/ovs.
60 .. _general-build-reqs:
65 To compile the userspace programs in the Open vSwitch distribution, you will
66 need the following software:
70 - A C compiler, such as:
76 - MSVC 2013. Refer to :doc:`windows` for additional Windows build
79 While OVS may be compatible with other compilers, optimal support for atomic
80 operations may be missing, making OVS very slow (see ``lib/ovs-atomic.h``).
82 - libssl, from OpenSSL, is optional but recommended if you plan to connect the
83 Open vSwitch to an OpenFlow controller. libssl is required to establish
84 confidentiality and authenticity in the connections from an Open vSwitch to
85 an OpenFlow controller. If libssl is installed, then Open vSwitch will
86 automatically build with support for it.
88 - libcap-ng, written by Steve Grubb, is optional but recommended. It is
89 required to run OVS daemons as a non-root user with dropped root privileges.
90 If libcap-ng is installed, then Open vSwitch will automatically build with
93 - Python 3.4 or later. You must also have the Python ``six`` library
94 version 1.4.0 or later.
96 - Unbound library, from http://www.unbound.net, is optional but recommended if
97 you want to enable ovs-vswitchd and other utilities to use DNS names when
98 specifying OpenFlow and OVSDB remotes. If unbound library is already
99 installed, then Open vSwitch will automatically build with support for it.
100 The environment variable OVS_RESOLV_CONF can be used to specify DNS server
101 configuration file (the default file on Linux is /etc/resolv.conf).
103 On Linux, you may choose to compile the kernel module that comes with the Open
104 vSwitch distribution or to use the kernel module built into the Linux kernel
105 (version 3.3 or later). See the :doc:`/faq/index` question "What features are
106 not available in the Open vSwitch kernel datapath that ships as part of the
107 upstream Linux kernel?" for more information on this trade-off. You may also
108 use the userspace-only implementation, at some cost in features and
109 performance. Refer to :doc:`userspace` for details.
111 To compile the kernel module on Linux, you must also install the
114 - A supported Linux kernel version.
116 For optional support of ingress policing, you must enable kernel
117 configuration options ``NET_CLS_BASIC``, ``NET_SCH_INGRESS``, and
118 ``NET_ACT_POLICE``, either built-in or as modules. ``NET_CLS_POLICE`` is
119 obsolete and not needed.)
121 On kernels before 3.11, the ``ip_gre`` module, for GRE tunnels over IP
122 (``NET_IPGRE``), must not be loaded or compiled in.
124 To configure HTB or HFSC quality of service with Open vSwitch, you must
125 enable the respective configuration options.
127 To use Open vSwitch support for TAP devices, you must enable ``CONFIG_TUN``.
129 - To build a kernel module, you need the same version of GCC that was used to
132 - A kernel build directory corresponding to the Linux kernel image the module
133 is to run on. Under Debian and Ubuntu, for example, each linux-image package
134 containing a kernel binary has a corresponding linux-headers package with
135 the required build infrastructure.
137 If you are working from a Git tree or snapshot (instead of from a distribution
138 tarball), or if you modify the Open vSwitch build system or the database
139 schema, you will also need the following software:
141 - Autoconf version 2.63 or later.
143 - Automake version 1.10 or later.
145 - libtool version 2.4 or later. (Older versions might work too.)
147 The datapath tests for userspace and Linux datapaths also rely upon:
149 - pyftpdlib. Version 1.2.0 is known to work. Earlier versions should
152 - GNU wget. Version 1.16 is known to work. Earlier versions should also
155 - netcat. Several common implementations are known to work.
157 - curl. Version 7.47.0 is known to work. Earlier versions should also work.
159 - tftpy. Version 0.6.2 is known to work. Earlier versions should also work.
161 - netstat. Available from various distro specific packages
163 The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in formats
164 other than plain text, only if you have the following:
166 - dot from graphviz (http://www.graphviz.org/).
168 If you are going to extensively modify Open vSwitch, consider installing the
169 following to obtain better warnings:
171 - "sparse" version 0.5.1 or later
172 (https://git.kernel.org/pub/scm/devel/sparse/sparse.git/).
176 - clang, version 3.4 or later
178 - flake8 along with the hacking flake8 plugin (for Python code). The automatic
179 flake8 check that runs against Python code has some warnings enabled that
180 come from the "hacking" flake8 plugin. If it's not installed, the warnings
181 just won't occur until it's run on a system with "hacking" installed.
183 You may find the ovs-dev script found in ``utilities/ovs-dev.py`` useful.
185 .. _general-install-reqs:
187 Installation Requirements
188 -------------------------
190 The machine you build Open vSwitch on may not be the one you run it on. To
191 simply install and run Open vSwitch you require the following software:
193 - Shared libraries compatible with those used for the build.
195 - On Linux, if you want to use the kernel-based datapath (which is the most
196 common use case), then a kernel with a compatible kernel module. This
197 can be a kernel module built with Open vSwitch (e.g. in the previous
198 step), or the kernel module that accompanies Linux 3.3 and later. Open
199 vSwitch features and performance can vary based on the module and the
200 kernel. Refer to :doc:`/faq/releases` for more information.
202 - For optional support of ingress policing on Linux, the "tc" program
203 from iproute2 (part of all major distributions and available at
204 https://wiki.linuxfoundation.org/networking/iproute2).
206 - Python 3.4 or later. You must also have the Python six library
207 version 1.4.0 or later.
209 On Linux you should ensure that ``/dev/urandom`` exists. To support TAP
210 devices, you must also ensure that ``/dev/net/tun`` exists.
212 .. _general-bootstrapping:
217 This step is not needed if you have downloaded a released tarball. If
218 you pulled the sources directly from an Open vSwitch Git tree or got a
219 Git tree snapshot, then run boot.sh in the top source directory to build
220 the "configure" script::
224 .. _general-configuring:
229 Configure the package by running the configure script. You can usually
230 invoke configure without any arguments. For example::
234 By default all files are installed under ``/usr/local``. Open vSwitch also
235 expects to find its database in ``/usr/local/etc/openvswitch`` by default. If
236 you want to install all files into, e.g., ``/usr`` and ``/var`` instead of
237 ``/usr/local`` and ``/usr/local/var`` and expect to use ``/etc/openvswitch`` as
238 the default database directory, add options as shown here::
240 $ ./configure --prefix=/usr --localstatedir=/var --sysconfdir=/etc
244 Open vSwitch installed with packages like .rpm (e.g. via ``yum install`` or
245 ``rpm -ivh``) and .deb (e.g. via ``apt-get install`` or ``dpkg -i``) use the
246 above configure options.
248 By default, static libraries are built and linked against. If you want to use
249 shared libraries instead::
251 $ ./configure --enable-shared
253 To use a specific C compiler for compiling Open vSwitch user programs, also
254 specify it on the configure command line, like so::
256 $ ./configure CC=gcc-4.2
258 To use 'clang' compiler::
260 $ ./configure CC=clang
262 To supply special flags to the C compiler, specify them as ``CFLAGS`` on the
263 configure command line. If you want the default CFLAGS, which include ``-g`` to
264 build debug symbols and ``-O2`` to enable optimizations, you must include them
265 yourself. For example, to build with the default CFLAGS plus ``-mssse3``, you
266 might run configure as follows::
268 $ ./configure CFLAGS="-g -O2 -mssse3"
270 For efficient hash computation special flags can be passed to leverage built-in
271 intrinsics. For example on X86_64 with SSE4.2 instruction set support, CRC32
272 intrinsics can be used by passing ``-msse4.2``::
274 $ ./configure CFLAGS="-g -O2 -msse4.2"`
276 Also builtin popcnt instruction can be used to speedup the counting of the
277 bits set in an integer. For example on X86_64 with POPCNT support, it can be
278 enabled by passing ``-mpopcnt``::
280 $ ./configure CFLAGS="-g -O2 -mpopcnt"`
282 If you are on a different processor and don't know what flags to choose, it is
283 recommended to use ``-march=native`` settings::
285 $ ./configure CFLAGS="-g -O2 -march=native"
287 With this, GCC will detect the processor and automatically set appropriate
288 flags for it. This should not be used if you are compiling OVS outside the
292 CFLAGS are not applied when building the Linux kernel module. Custom CFLAGS
293 for the kernel module are supplied using the ``EXTRA_CFLAGS`` variable when
294 running make. For example::
296 $ make EXTRA_CFLAGS="-Wno-error=date-time"
298 If you are a developer and want to enable Address Sanitizer for debugging
299 purposes, at about a 2x runtime cost, you can add
300 ``-fsanitize=address -fno-omit-frame-pointer -fno-common`` to CFLAGS. For
303 $ ./configure CFLAGS="-g -O2 -fsanitize=address -fno-omit-frame-pointer -fno-common"
305 To build the Linux kernel module, so that you can run the kernel-based switch,
306 pass the location of the kernel build directory on ``--with-linux``. For
307 example, to build for a running instance of Linux::
309 $ ./configure --with-linux=/lib/modules/$(uname -r)/build
312 If ``--with-linux`` requests building for an unsupported version of Linux,
313 then ``configure`` will fail with an error message. Refer to the
314 :doc:`/faq/index` for advice in that case.
316 If you wish to build the kernel module for an architecture other than the
317 architecture of the machine used for the build, you may specify the kernel
318 architecture string using the KARCH variable when invoking the configure
319 script. For example, to build for MIPS with Linux::
321 $ ./configure --with-linux=/path/to/linux KARCH=mips
323 If you plan to do much Open vSwitch development, you might want to add
324 ``--enable-Werror``, which adds the ``-Werror`` option to the compiler command
325 line, turning warnings into errors. That makes it impossible to miss warnings
326 generated by the build. For example::
328 $ ./configure --enable-Werror
330 If you're building with GCC, then, for improved warnings, install ``sparse``
331 (see "Prerequisites") and enable it for the build by adding
332 ``--enable-sparse``. Use this with ``--enable-Werror`` to avoid missing both
333 compiler and ``sparse`` warnings, e.g.::
335 $ ./configure --enable-Werror --enable-sparse
337 To build with gcov code coverage support, add ``--enable-coverage``::
339 $ ./configure --enable-coverage
341 The configure script accepts a number of other options and honors additional
342 environment variables. For a full list, invoke configure with the ``--help``
347 You can also run configure from a separate build directory. This is helpful if
348 you want to build Open vSwitch in more than one way from a single source
349 directory, e.g. to try out both GCC and Clang builds, or to build kernel
350 modules for more than one Linux version. For example::
352 $ mkdir _gcc && (cd _gcc && ./configure CC=gcc)
353 $ mkdir _clang && (cd _clang && ./configure CC=clang)
355 Under certain loads the ovsdb-server and other components perform better when
356 using the jemalloc memory allocator, instead of the glibc memory allocator. If
357 you wish to link with jemalloc add it to LIBS::
359 $ ./configure LIBS=-ljemalloc
361 .. _general-building:
366 1. Run GNU make in the build directory, e.g.::
370 or if GNU make is installed as "gmake"::
374 If you used a separate build directory, run make or gmake from that
381 Some versions of Clang and ccache are not completely compatible. If you
382 see unusual warnings when you use both together, consider disabling
385 2. Consider running the testsuite. Refer to :doc:`/topics/testing` for
388 3. Run ``make install`` to install the executables and manpages into the
389 running system, by default under ``/usr/local``::
393 5. If you built kernel modules, you may install them, e.g.::
395 $ make modules_install
397 It is possible that you already had a Open vSwitch kernel module installed
398 on your machine that came from upstream Linux (in a different directory). To
399 make sure that you load the Open vSwitch kernel module you built from this
400 repository, you should create a ``depmod.d`` file that prefers your newly
401 installed kernel modules over the kernel modules from upstream Linux. The
402 following snippet of code achieves the same::
404 $ config_file="/etc/depmod.d/openvswitch.conf"
405 $ for module in datapath/linux/*.ko; do
406 modname="$(basename ${module})"
407 echo "override ${modname%.ko} * extra" >> "$config_file"
408 echo "override ${modname%.ko} * weak-updates" >> "$config_file"
412 Finally, load the kernel modules that you need. e.g.::
414 $ /sbin/modprobe openvswitch
416 To verify that the modules have been loaded, run ``/sbin/lsmod`` and check
417 that openvswitch is listed::
419 $ /sbin/lsmod | grep openvswitch
422 If the ``modprobe`` operation fails, look at the last few kernel log
423 messages (e.g. with ``dmesg | tail``). Generally, issues like this occur
424 when Open vSwitch is built for a kernel different from the one into which
425 you are trying to load it. Run ``modinfo`` on ``openvswitch.ko`` and on a
426 module built for the running kernel, e.g.::
428 $ /sbin/modinfo openvswitch.ko
429 $ /sbin/modinfo /lib/modules/$(uname -r)/kernel/net/bridge/bridge.ko
431 Compare the "vermagic" lines output by the two commands. If they differ,
432 then Open vSwitch was built for the wrong kernel.
434 If you decide to report a bug or ask a question related to module loading,
435 include the output from the ``dmesg`` and ``modinfo`` commands mentioned
438 .. _general-starting:
443 On Unix-alike systems, such as BSDs and Linux, starting the Open vSwitch
444 suite of daemons is a simple process. Open vSwitch includes a shell script,
445 and helpers, called ovs-ctl which automates much of the tasks for starting
446 and stopping ovsdb-server, and ovs-vswitchd. After installation, the daemons
447 can be started by using the ovs-ctl utility. This will take care to setup
448 initial conditions, and start the daemons in the correct order. The ovs-ctl
449 utility is located in '$(pkgdatadir)/scripts', and defaults to
450 '/usr/local/share/openvswitch/scripts'. An example after install might be::
452 $ export PATH=$PATH:/usr/local/share/openvswitch/scripts
455 Additionally, the ovs-ctl script allows starting / stopping the daemons
456 individually using specific options. To start just the ovsdb-server::
458 $ export PATH=$PATH:/usr/local/share/openvswitch/scripts
459 $ ovs-ctl --no-ovs-vswitchd start
461 Likewise, to start just the ovs-vswitchd::
463 $ export PATH=$PATH:/usr/local/share/openvswitch/scripts
464 $ ovs-ctl --no-ovsdb-server start
466 Refer to ovs-ctl(8) for more information on ovs-ctl.
468 In addition to using the automated script to start Open vSwitch, you may
469 wish to manually start the various daemons. Before starting ovs-vswitchd
470 itself, you need to start its configuration database, ovsdb-server. Each
471 machine on which Open vSwitch is installed should run its own copy of
472 ovsdb-server. Before ovsdb-server itself can be started, configure a
473 database that it can use::
475 $ mkdir -p /usr/local/etc/openvswitch
476 $ ovsdb-tool create /usr/local/etc/openvswitch/conf.db \
477 vswitchd/vswitch.ovsschema
479 Configure ovsdb-server to use database created above, to listen on a Unix
480 domain socket, to connect to any managers specified in the database itself, and
481 to use the SSL configuration in the database::
483 $ mkdir -p /usr/local/var/run/openvswitch
484 $ ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \
485 --remote=db:Open_vSwitch,Open_vSwitch,manager_options \
486 --private-key=db:Open_vSwitch,SSL,private_key \
487 --certificate=db:Open_vSwitch,SSL,certificate \
488 --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \
489 --pidfile --detach --log-file
492 If you built Open vSwitch without SSL support, then omit ``--private-key``,
493 ``--certificate``, and ``--bootstrap-ca-cert``.)
495 Initialize the database using ovs-vsctl. This is only necessary the first time
496 after you create the database with ovsdb-tool, though running it at any time is
499 $ ovs-vsctl --no-wait init
501 Start the main Open vSwitch daemon, telling it to connect to the same Unix
504 $ ovs-vswitchd --pidfile --detach --log-file
506 Starting OVS in container
507 -------------------------
509 For ovs vswitchd, we need to load ovs kernel modules on host.
511 Hence, OVS containers kernel version needs to be same as that of host kernel.
513 Export following variables in .env and place it under
516 $ OVS_BRANCH=<BRANCH>
517 $ OVS_VERSION=<VERSION>
518 $ DISTRO=<LINUX_DISTRO>
519 $ KERNEL_VERSION=<LINUX_KERNEL_VERSION>
520 $ GITHUB_SRC=<GITHUB_URL>
521 $ DOCKER_REPO=<REPO_TO_PUSH_IMAGE>
523 To build ovs modules::
525 $ cd utilities/docker
528 Compiled Modules will be tagged with docker image
530 To Push ovs modules::
534 OVS docker image will be pushed to specified docker repo.
536 Start ovsdb-server using below command::
538 $ docker run -itd --net=host --name=ovsdb-server \
539 <docker_repo>:<tag> ovsdb-server
541 Start ovs-vswitchd with priviledged mode as it needs to load kernel module in
542 host using below command::
544 $ docker run -itd --net=host --name=ovs-vswitchd \
545 --volumes-from=ovsdb-server -v /lib:/lib --privileged \
546 <docker_repo>:<tag> ovs-vswitchd
549 The debian docker file uses ubuntu 16.04 as a base image for reference.
551 User can use any other base image for debian, e.g. u14.04, etc.
553 RHEL based docker build support needs to be added.
558 At this point you can use ovs-vsctl to set up bridges and other Open vSwitch
559 features. For example, to create a bridge named ``br0`` and add ports ``eth0``
560 and ``vif1.0`` to it::
562 $ ovs-vsctl add-br br0
563 $ ovs-vsctl add-port br0 eth0
564 $ ovs-vsctl add-port br0 vif1.0
566 Refer to ovs-vsctl(8) for more details. You may also wish to refer to
567 :doc:`/topics/testing` for information on more generic testing of OVS.
569 When using ovs in container, exec to container to run above commands::
571 $ docker exec -it <ovsdb-server/ovs-vswitchd> /bin/bash
576 When you upgrade Open vSwitch from one version to another you should also
577 upgrade the database schema:
580 The following manual steps may also be accomplished by using ovs-ctl to
581 stop and start the daemons after upgrade. The ovs-ctl script will
582 automatically upgrade the schema.
584 1. Stop the Open vSwitch daemons, e.g.::
586 $ kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid`
588 2. Install the new Open vSwitch release by using the same configure options as
589 was used for installing the previous version. If you do not use the same
590 configure options, you can end up with two different versions of Open
591 vSwitch executables installed in different locations.
593 3. Upgrade the database, in one of the following two ways:
595 - If there is no important data in your database, then you may delete the
596 database file and recreate it with ovsdb-tool, following the instructions
597 under "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD".
599 - If you want to preserve the contents of your database, back it up first,
600 then use ``ovsdb-tool convert`` to upgrade it, e.g.::
602 $ ovsdb-tool convert /usr/local/etc/openvswitch/conf.db \
603 vswitchd/vswitch.ovsschema
605 4. Start the Open vSwitch daemons as described under `Starting`_ above.
610 Upgrading Open vSwitch from one version to the next version with minimum
611 disruption of traffic going through the system that is using that Open vSwitch
612 needs some considerations:
614 1. If the upgrade only involves upgrading the userspace utilities and daemons
615 of Open vSwitch, make sure that the new userspace version is compatible with
616 the previously loaded kernel module.
618 2. An upgrade of userspace daemons means that they have to be restarted.
619 Restarting the daemons means that the OpenFlow flows in the ovs-vswitchd
620 daemon will be lost. One way to restore the flows is to let the controller
621 re-populate it. Another way is to save the previous flows using a utility
622 like ovs-ofctl and then re-add them after the restart. Restoring the old
623 flows is accurate only if the new Open vSwitch interfaces retain the old
626 3. When the new userspace daemons get restarted, they automatically flush the
627 old flows setup in the kernel. This can be expensive if there are hundreds
628 of new flows that are entering the kernel but userspace daemons are busy
629 setting up new userspace flows from either the controller or an utility like
630 ovs-ofctl. Open vSwitch database provides an option to solve this problem
631 through the ``other_config:flow-restore-wait`` column of the
632 ``Open_vSwitch`` table. Refer to the ovs-vswitchd.conf.db(5) manpage for
635 4. If the upgrade also involves upgrading the kernel module, the old kernel
636 module needs to be unloaded and the new kernel module should be loaded. This
637 means that the kernel network devices belonging to Open vSwitch is recreated
638 and the kernel flows are lost. The downtime of the traffic can be reduced if
639 the userspace daemons are restarted immediately and the userspace flows are
640 restored as soon as possible.
642 5. When upgrading ovs running in container on host that is managed by ovn,
643 simply stop the docker container, remove and re-run with new docker image
644 that has newer ovs version.
646 6. When running ovs in container, if ovs is used in bridged mode where
647 management interface is managed by ovs, docker restart will result in loss
648 of network connectivity. Hence, make sure to delete the bridge mapping of
649 physical interface from ovs, upgrade ovs via docker and then add back the
650 interface to ovs bridge. This mapping need not be deleted in case of multi
651 nics if management interface is not managed by ovs.
654 The ovs-ctl utility's ``restart`` function only restarts the userspace daemons,
655 makes sure that the 'ofport' values remain consistent across restarts, restores
656 userspace flows using the ovs-ofctl utility and also uses the
657 ``other_config:flow-restore-wait`` column to keep the traffic downtime to the
658 minimum. The ovs-ctl utility's ``force-reload-kmod`` function does all of the
659 above, but also replaces the old kernel module with the new one. Open vSwitch
660 startup scripts for Debian, XenServer and RHEL use ovs-ctl's functions and it
661 is recommended that these functions be used for other software platforms too.
666 Report problems to bugs@openvswitch.org.