]>
Commit | Line | Data |
---|---|---|
542cc9bb TG |
1 | How to Install Open vSwitch on Linux, FreeBSD and NetBSD |
2 | ======================================================== | |
4b11d5e8 BP |
3 | |
4 | This document describes how to build and install Open vSwitch on a | |
76d5beb9 YT |
5 | generic Linux, FreeBSD, or NetBSD host. For specifics around installation |
6 | on a specific platform, please see one of these files: | |
4b11d5e8 | 7 | |
9feb1017 TG |
8 | - [INSTALL.Debian.md] |
9 | - [INSTALL.Fedora.md] | |
10 | - [INSTALL.RHEL.md] | |
11 | - [INSTALL.XenServer.md] | |
12 | - [INSTALL.NetBSD.md] | |
620b1762 | 13 | - [INSTALL.Windows.md] |
9feb1017 | 14 | - [INSTALL.DPDK.md] |
4b11d5e8 BP |
15 | |
16 | Build Requirements | |
17 | ------------------ | |
18 | ||
19 | To compile the userspace programs in the Open vSwitch distribution, | |
20 | you will need the following software: | |
21 | ||
542cc9bb | 22 | - GNU make. |
4b11d5e8 | 23 | |
542cc9bb | 24 | - A C compiler, such as: |
8a6de510 | 25 | |
542cc9bb | 26 | * GCC 4.x. |
8a6de510 | 27 | |
542cc9bb TG |
28 | * Clang. Clang 3.4 and later provide useful static semantic |
29 | analysis and thread-safety checks. For Ubuntu, there are | |
30 | nightly built packages available on clang's website. | |
4b11d5e8 | 31 | |
620b1762 BP |
32 | * MSVC 2013. See [INSTALL.Windows] for additional Windows build |
33 | instructions. | |
34 | ||
542cc9bb TG |
35 | While OVS may be compatible with other compilers, optimal |
36 | support for atomic operations may be missing, making OVS very | |
37 | slow (see lib/ovs-atomic.h). | |
29d204ef | 38 | |
542cc9bb TG |
39 | - libssl, from OpenSSL, is optional but recommended if you plan to |
40 | connect the Open vSwitch to an OpenFlow controller. libssl is | |
41 | required to establish confidentiality and authenticity in the | |
42 | connections from an Open vSwitch to an OpenFlow controller. If | |
43 | libssl is installed, then Open vSwitch will automatically build | |
44 | with support for it. | |
4b11d5e8 | 45 | |
1bbebfb7 AZ |
46 | - libcap-ng, written by Steve Grubb, is optional but recommended. It |
47 | is required to run OVS daemons as a non-root user with dropped root | |
48 | privileges. If libcap-ng is installed, then Open vSwitch will | |
49 | automatically build with support for it. | |
50 | ||
73eb682e | 51 | - Python 2.7. You must also have the Python six library. |
deb64473 | 52 | |
c6435221 BP |
53 | On Linux, you may choose to compile the kernel module that comes with |
54 | the Open vSwitch distribution or to use the kernel module built into | |
9feb1017 TG |
55 | the Linux kernel (version 3.3 or later). See the [FAQ.md] question |
56 | "What features are not available in the Open vSwitch kernel datapath that | |
c6435221 BP |
57 | ships as part of the upstream Linux kernel?" for more information on |
58 | this trade-off. You may also use the userspace-only implementation, | |
9feb1017 TG |
59 | at some cost in features and performance (see [INSTALL.userspace.md] |
60 | for details). To compile the kernel module on Linux, you must also | |
c6435221 | 61 | install the following: |
4b11d5e8 | 62 | |
9feb1017 | 63 | - A supported Linux kernel version. Please refer to [README.md] for a |
542cc9bb | 64 | list of supported versions. |
4b11d5e8 | 65 | |
542cc9bb TG |
66 | For optional support of ingress policing, you must enable kernel |
67 | configuration options NET_CLS_BASIC, NET_SCH_INGRESS, and | |
68 | NET_ACT_POLICE, either built-in or as modules. (NET_CLS_POLICE is | |
69 | obsolete and not needed.) | |
4b11d5e8 | 70 | |
8063e095 PS |
71 | On kernels before 3.11, the ip_gre module, for GRE tunnels over IP |
72 | (NET_IPGRE), must not be loaded or compiled in. | |
6f470982 | 73 | |
542cc9bb TG |
74 | To configure HTB or HFSC quality of service with Open vSwitch, |
75 | you must enable the respective configuration options. | |
c9d3af4e | 76 | |
542cc9bb TG |
77 | To use Open vSwitch support for TAP devices, you must enable |
78 | CONFIG_TUN. | |
26bb189d | 79 | |
542cc9bb TG |
80 | - To build a kernel module, you need the same version of GCC that |
81 | was used to build that kernel. | |
4b11d5e8 | 82 | |
542cc9bb TG |
83 | - A kernel build directory corresponding to the Linux kernel image |
84 | the module is to run on. Under Debian and Ubuntu, for example, | |
85 | each linux-image package containing a kernel binary has a | |
86 | corresponding linux-headers package with the required build | |
87 | infrastructure. | |
4b11d5e8 BP |
88 | |
89 | If you are working from a Git tree or snapshot (instead of from a | |
c9d3af4e BP |
90 | distribution tarball), or if you modify the Open vSwitch build system |
91 | or the database schema, you will also need the following software: | |
4b11d5e8 | 92 | |
542cc9bb | 93 | - Autoconf version 2.63 or later. |
4b11d5e8 | 94 | |
542cc9bb | 95 | - Automake version 1.10 or later. |
4b11d5e8 | 96 | |
542cc9bb | 97 | - libtool version 2.4 or later. (Older versions might work too.) |
195b5c35 | 98 | |
c9d3af4e BP |
99 | To run the unit tests, you also need: |
100 | ||
542cc9bb TG |
101 | - Perl. Version 5.10.1 is known to work. Earlier versions should |
102 | also work. | |
c9d3af4e | 103 | |
a5ae88ff AA |
104 | The ovs-vswitchd.conf.db(5) manpage will include an E-R diagram, in |
105 | formats other than plain text, only if you have the following: | |
f8d739a9 | 106 | |
542cc9bb | 107 | - "dot" from graphviz (http://www.graphviz.org/). |
f8d739a9 | 108 | |
542cc9bb TG |
109 | - Perl. Version 5.10.1 is known to work. Earlier versions should |
110 | also work. | |
c9d3af4e | 111 | |
f8f26e98 BP |
112 | If you are going to extensively modify Open vSwitch, please consider |
113 | installing the following to obtain better warnings: | |
114 | ||
542cc9bb TG |
115 | - "sparse" version 0.4.4 or later |
116 | (http://www.kernel.org/pub/software/devel/sparse/dist/). | |
f8f26e98 | 117 | |
542cc9bb | 118 | - GNU make. |
f8f26e98 | 119 | |
542cc9bb | 120 | - clang, version 3.4 or later |
97be1538 | 121 | |
115d8719 RB |
122 | - flake8 (for Python code) |
123 | ||
fef5244f EJ |
124 | Also, you may find the ovs-dev script found in utilities/ovs-dev.py useful. |
125 | ||
4b11d5e8 BP |
126 | Installation Requirements |
127 | ------------------------- | |
128 | ||
129 | The machine on which Open vSwitch is to be installed must have the | |
130 | following software: | |
131 | ||
542cc9bb | 132 | - libc compatible with the libc used for build. |
4b11d5e8 | 133 | |
542cc9bb TG |
134 | - libssl compatible with the libssl used for build, if OpenSSL was |
135 | used for the build. | |
4b11d5e8 | 136 | |
542cc9bb | 137 | - On Linux, the same kernel version configured as part of the build. |
4b11d5e8 | 138 | |
542cc9bb TG |
139 | - For optional support of ingress policing on Linux, the "tc" program |
140 | from iproute2 (part of all major distributions and available at | |
141 | http://www.linux-foundation.org/en/Net:Iproute2). | |
4b11d5e8 | 142 | |
73eb682e RB |
143 | - Python 2.7. You must also have the Python six library. |
144 | ||
f6eb6b20 GL |
145 | On Linux you should ensure that /dev/urandom exists. To support TAP |
146 | devices, you must also ensure that /dev/net/tun exists. | |
6e8e271c | 147 | |
76d5beb9 YT |
148 | Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD |
149 | ================================================================= | |
4b11d5e8 | 150 | |
e9e85443 FL |
151 | Once you have installed all the prerequisites listed above in the |
152 | Base Prerequisites section, follow the procedures below to bootstrap, | |
153 | to configure and to build the code. | |
4b11d5e8 | 154 | |
e9e85443 FL |
155 | Bootstrapping the Sources |
156 | ------------------------- | |
157 | ||
158 | This step is not needed if you have downloaded a released tarball. | |
159 | If you pulled the sources directly from an Open vSwitch Git tree or | |
160 | got a Git tree snapshot, then run boot.sh in the top source directory | |
161 | to build the "configure" script. | |
30746a1b | 162 | |
542cc9bb | 163 | `% ./boot.sh` |
30746a1b | 164 | |
e9e85443 FL |
165 | |
166 | Configuring the Sources | |
167 | ----------------------- | |
168 | ||
169 | Configure the package by running the configure script. You can | |
170 | usually invoke configure without any arguments. For example: | |
4b11d5e8 | 171 | |
542cc9bb | 172 | `% ./configure` |
4b11d5e8 | 173 | |
109c01b1 GS |
174 | By default all files are installed under /usr/local. Open vSwitch also |
175 | expects to find its database in /usr/local/etc/openvswitch by default. | |
176 | If you want to install all files into, e.g., /usr and /var instead of | |
177 | /usr/local and /usr/local/var and expect to use /etc/openvswitch as the default | |
178 | database directory, add options as shown here: | |
4b11d5e8 | 179 | |
109c01b1 GS |
180 | `% ./configure --prefix=/usr --localstatedir=/var --sysconfdir=/etc` |
181 | ||
182 | Note that the Open vSwitch installed with packages like .rpm (e.g. via 'yum | |
183 | install' or 'rpm -ivh') and .deb (e.g. via 'apt-get install' or 'dpkg -i') use | |
184 | the above configure options. | |
4b11d5e8 | 185 | |
e9e85443 FL |
186 | By default, static libraries are built and linked against. If you |
187 | want to use shared libraries instead: | |
7748423a | 188 | |
e0512257 | 189 | `% ./configure --enable-shared` |
7748423a | 190 | |
e9e85443 FL |
191 | To use a specific C compiler for compiling Open vSwitch user |
192 | programs, also specify it on the configure command line, like so: | |
4b11d5e8 | 193 | |
542cc9bb | 194 | `% ./configure CC=gcc-4.2` |
4b11d5e8 | 195 | |
e9e85443 | 196 | To use 'clang' compiler: |
97be1538 | 197 | |
542cc9bb | 198 | `% ./configure CC=clang` |
97be1538 | 199 | |
73c33892 BP |
200 | To supply special flags to the C compiler, specify them as CFLAGS on |
201 | the configure command line. If you want the default CFLAGS, which | |
202 | include "-g" to build debug symbols and "-O2" to enable optimizations, | |
203 | you must include them yourself. For example, to build with the | |
204 | default CFLAGS plus "-mssse3", you might run configure as follows: | |
205 | ||
206 | `% ./configure CFLAGS="-g -O2 -mssse3"` | |
207 | ||
4f7e5c27 RB |
208 | Note that these CFLAGS are not applied when building the Linux |
209 | kernel module. Custom CFLAGS for the kernel module are supplied | |
210 | using the EXTRA_CFLAGS variable when running make. So, for example: | |
211 | ||
e0512257 | 212 | `% make EXTRA_CFLAGS="-Wno-error=date-time"` |
4f7e5c27 | 213 | |
e9e85443 FL |
214 | To build the Linux kernel module, so that you can run the |
215 | kernel-based switch, pass the location of the kernel build | |
216 | directory on --with-linux. For example, to build for a running | |
217 | instance of Linux: | |
4b11d5e8 | 218 | |
542cc9bb | 219 | `% ./configure --with-linux=/lib/modules/`uname -r`/build` |
4b11d5e8 | 220 | |
e9e85443 FL |
221 | If --with-linux requests building for an unsupported version of |
222 | Linux, then "configure" will fail with an error message. Please | |
223 | refer to the [FAQ.md] for advice in that case. | |
a7ae9380 | 224 | |
e9e85443 FL |
225 | If you wish to build the kernel module for an architecture other |
226 | than the architecture of the machine used for the build, you may | |
227 | specify the kernel architecture string using the KARCH variable | |
228 | when invoking the configure script. For example, to build for MIPS | |
229 | with Linux: | |
4b11d5e8 | 230 | |
542cc9bb | 231 | `% ./configure --with-linux=/path/to/linux KARCH=mips` |
4b11d5e8 | 232 | |
e9e85443 FL |
233 | If you plan to do much Open vSwitch development, you might want to |
234 | add --enable-Werror, which adds the -Werror option to the compiler | |
235 | command line, turning warnings into errors. That makes it | |
236 | impossible to miss warnings generated by the build. | |
ad367b28 | 237 | |
e9e85443 FL |
238 | To build with gcov code coverage support, add --enable-coverage, |
239 | e.g.: | |
e3c7ed29 | 240 | |
542cc9bb | 241 | `% ./configure --enable-coverage` |
e3c7ed29 | 242 | |
e9e85443 FL |
243 | The configure script accepts a number of other options and honors |
244 | additional environment variables. For a full list, invoke | |
245 | configure with the --help option. | |
4b11d5e8 | 246 | |
e9e85443 FL |
247 | You can also run configure from a separate build directory. This |
248 | is helpful if you want to build Open vSwitch in more than one way | |
249 | from a single source directory, e.g. to try out both GCC and Clang | |
250 | builds, or to build kernel modules for more than one Linux version. | |
251 | Here is an example: | |
ef7889b4 | 252 | |
e0512257 | 253 | `% mkdir _gcc && (cd _gcc && ../configure CC=gcc)` |
542cc9bb | 254 | `% mkdir _clang && (cd _clang && ../configure CC=clang)` |
ef7889b4 | 255 | |
48d3d488 RBE |
256 | Under certains loads the ovsdb-server and other components perform |
257 | better when using the jemalloc memory allocator, instead of the glibc | |
258 | memory allocator. | |
259 | ||
260 | If you wish to link with jemalloc add it to LIBS: | |
261 | ||
262 | `% ./configure LIBS=-ljemalloc` | |
e9e85443 FL |
263 | |
264 | Building the Sources | |
265 | -------------------- | |
266 | ||
267 | 1. Run GNU make in the build directory, e.g.: | |
4b11d5e8 | 268 | |
542cc9bb | 269 | `% make` |
4b11d5e8 | 270 | |
380b39f7 BP |
271 | or if GNU make is installed as "gmake": |
272 | ||
542cc9bb | 273 | `% gmake` |
f6eb6b20 | 274 | |
ef7889b4 BP |
275 | If you used a separate build directory, run make or gmake from that |
276 | directory, e.g.: | |
277 | ||
e0512257 | 278 | `% make -C _gcc` |
542cc9bb | 279 | `% make -C _clang` |
ef7889b4 | 280 | |
e9e85443 FL |
281 | For improved warnings if you installed "sparse" (see "Prerequisites"), |
282 | add C=1 to the command line. | |
f8f26e98 | 283 | |
86b3f7e1 BP |
284 | Some versions of Clang and ccache are not completely compatible. |
285 | If you see unusual warnings when you use both together, consider | |
286 | disabling ccache for use with Clang. | |
287 | ||
e9e85443 | 288 | 2. Consider running the testsuite. Refer to "Running the Testsuite" |
875ef81b | 289 | below, for instructions. |
4b11d5e8 | 290 | |
e9e85443 | 291 | 3. Become root by running "su" or another program. |
875ef81b | 292 | |
e9e85443 | 293 | 4. Run "make install" to install the executables and manpages into the |
4b11d5e8 BP |
294 | running system, by default under /usr/local. |
295 | ||
e9e85443 | 296 | 5. If you built kernel modules, you may install and load them, e.g.: |
4b11d5e8 | 297 | |
e0512257 | 298 | `% make modules_install` |
542cc9bb | 299 | `% /sbin/modprobe openvswitch` |
4b11d5e8 | 300 | |
4b11d5e8 | 301 | To verify that the modules have been loaded, run "/sbin/lsmod" and |
9b80f761 | 302 | check that openvswitch is listed. |
4b11d5e8 | 303 | |
542cc9bb TG |
304 | If the `modprobe` operation fails, look at the last few kernel log |
305 | messages (e.g. with `dmesg | tail`): | |
dd2d79ce | 306 | |
dd2d79ce BP |
307 | - Otherwise, the most likely problem is that Open vSwitch was |
308 | built for a kernel different from the one into which you are | |
542cc9bb | 309 | trying to load it. Run `modinfo` on openvswitch.ko and on |
dd2d79ce BP |
310 | a module built for the running kernel, e.g.: |
311 | ||
542cc9bb | 312 | ``` |
9b80f761 | 313 | % /sbin/modinfo openvswitch.ko |
dd2d79ce | 314 | % /sbin/modinfo /lib/modules/`uname -r`/kernel/net/bridge/bridge.ko |
542cc9bb | 315 | ``` |
dd2d79ce BP |
316 | |
317 | Compare the "vermagic" lines output by the two commands. If | |
318 | they differ, then Open vSwitch was built for the wrong kernel. | |
319 | ||
320 | - If you decide to report a bug or ask a question related to | |
542cc9bb TG |
321 | module loading, please include the output from the `dmesg` and |
322 | `modinfo` commands mentioned above. | |
dd2d79ce | 323 | |
e9e85443 | 324 | 6. Initialize the configuration database using ovsdb-tool, e.g.: |
4b11d5e8 | 325 | |
e0512257 | 326 | `% mkdir -p /usr/local/etc/openvswitch` |
542cc9bb | 327 | `% ovsdb-tool create /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema` |
4b11d5e8 | 328 | |
3b12adda BP |
329 | Startup |
330 | ======= | |
4b11d5e8 | 331 | |
3b12adda | 332 | Before starting ovs-vswitchd itself, you need to start its |
cb8141b2 BP |
333 | configuration database, ovsdb-server. Each machine on which Open |
334 | vSwitch is installed should run its own copy of ovsdb-server. | |
566b8c8d BP |
335 | Configure it to use the database you created during installation (as |
336 | explained above), to listen on a Unix domain socket, to connect to any | |
337 | managers specified in the database itself, and to use the SSL | |
8084a280 BP |
338 | configuration in the database: |
339 | ||
e0512257 | 340 | ``` |
29701194 | 341 | % ovsdb-server --remote=punix:/usr/local/var/run/openvswitch/db.sock \ |
6faab099 JP |
342 | --remote=db:Open_vSwitch,Open_vSwitch,manager_options \ |
343 | --private-key=db:Open_vSwitch,SSL,private_key \ | |
344 | --certificate=db:Open_vSwitch,SSL,certificate \ | |
345 | --bootstrap-ca-cert=db:Open_vSwitch,SSL,ca_cert \ | |
29701194 | 346 | --pidfile --detach |
e0512257 | 347 | ``` |
3b12adda | 348 | |
d3e3fb58 BP |
349 | (If you built Open vSwitch without SSL support, then omit |
350 | --private-key, --certificate, and --bootstrap-ca-cert.) | |
351 | ||
de4f3c10 | 352 | Then initialize the database using ovs-vsctl. This is only |
332b4e09 BP |
353 | necessary the first time after you create the database with |
354 | ovsdb-tool (but running it at any time is harmless): | |
355 | ||
e0512257 | 356 | `% ovs-vsctl --no-wait init` |
332b4e09 | 357 | |
3b12adda BP |
358 | Then start the main Open vSwitch daemon, telling it to connect to the |
359 | same Unix domain socket: | |
360 | ||
e0512257 | 361 | `% ovs-vswitchd --pidfile --detach` |
3b12adda BP |
362 | |
363 | Now you may use ovs-vsctl to set up bridges and other Open vSwitch | |
364 | features. For example, to create a bridge named br0 and add ports | |
365 | eth0 and vif1.0 to it: | |
366 | ||
e0512257 JR |
367 | `% ovs-vsctl add-br br0` |
368 | `% ovs-vsctl add-port br0 eth0` | |
369 | `% ovs-vsctl add-port br0 vif1.0` | |
3b12adda BP |
370 | |
371 | Please refer to ovs-vsctl(8) for more details. | |
4b11d5e8 | 372 | |
8b055d92 BP |
373 | Upgrading |
374 | ========= | |
375 | ||
376 | When you upgrade Open vSwitch from one version to another, you should | |
377 | also upgrade the database schema: | |
378 | ||
379 | 1. Stop the Open vSwitch daemons, e.g.: | |
380 | ||
542cc9bb | 381 | ``` |
012f5c4b | 382 | % kill `cd /usr/local/var/run/openvswitch && cat ovsdb-server.pid ovs-vswitchd.pid` |
542cc9bb | 383 | ``` |
8b055d92 | 384 | |
109c01b1 GS |
385 | 2. Install the new Open vSwitch release by using the same configure options as |
386 | was used for installing the previous version. If you do not use the same | |
387 | configure options, you can end up with two different versions of Open vSwitch | |
388 | executables installed in different locations. | |
8b055d92 BP |
389 | |
390 | 3. Upgrade the database, in one of the following two ways: | |
391 | ||
392 | - If there is no important data in your database, then you may | |
393 | delete the database file and recreate it with ovsdb-tool, | |
394 | following the instructions under "Building and Installing Open | |
76d5beb9 | 395 | vSwitch for Linux, FreeBSD or NetBSD". |
8b055d92 BP |
396 | |
397 | - If you want to preserve the contents of your database, back it | |
398 | up first, then use "ovsdb-tool convert" to upgrade it, e.g.: | |
399 | ||
542cc9bb | 400 | `% ovsdb-tool convert /usr/local/etc/openvswitch/conf.db vswitchd/vswitch.ovsschema` |
8b055d92 BP |
401 | |
402 | 4. Start the Open vSwitch daemons as described under "Building and | |
76d5beb9 | 403 | Installing Open vSwitch for Linux, FreeBSD or NetBSD" above. |
8b055d92 | 404 | |
4e375050 GS |
405 | Hot Upgrading |
406 | ============= | |
407 | Upgrading Open vSwitch from one version to the next version with minimum | |
408 | disruption of traffic going through the system that is using that Open vSwitch | |
409 | needs some considerations: | |
410 | ||
411 | 1. If the upgrade only involves upgrading the userspace utilities and daemons | |
412 | of Open vSwitch, make sure that the new userspace version is compatible with | |
413 | the previously loaded kernel module. | |
414 | ||
415 | 2. An upgrade of userspace daemons means that they have to be restarted. | |
ea274df9 | 416 | Restarting the daemons means that the OpenFlow flows in the ovs-vswitchd daemon |
4e375050 GS |
417 | will be lost. One way to restore the flows is to let the controller |
418 | re-populate it. Another way is to save the previous flows using a utility | |
419 | like ovs-ofctl and then re-add them after the restart. Restoring the old flows | |
420 | is accurate only if the new Open vSwitch interfaces retain the old 'ofport' | |
421 | values. | |
422 | ||
423 | 3. When the new userspace daemons get restarted, they automatically flush | |
424 | the old flows setup in the kernel. This can be expensive if there are hundreds | |
425 | of new flows that are entering the kernel but userspace daemons are busy | |
426 | setting up new userspace flows from either the controller or an utility like | |
427 | ovs-ofctl. Open vSwitch database provides an option to solve this problem | |
428 | through the other_config:flow-restore-wait column of the Open_vSwitch table. | |
429 | Refer to the ovs-vswitchd.conf.db(5) manpage for details. | |
430 | ||
431 | 4. If the upgrade also involves upgrading the kernel module, the old kernel | |
432 | module needs to be unloaded and the new kernel module should be loaded. This | |
433 | means that the kernel network devices belonging to Open vSwitch is recreated | |
434 | and the kernel flows are lost. The downtime of the traffic can be reduced | |
435 | if the userspace daemons are restarted immediately and the userspace flows | |
436 | are restored as soon as possible. | |
437 | ||
438 | The ovs-ctl utility's "restart" function only restarts the userspace daemons, | |
439 | makes sure that the 'ofport' values remain consistent across restarts, restores | |
440 | userspace flows using the ovs-ofctl utility and also uses the | |
441 | other_config:flow-restore-wait column to keep the traffic downtime to the | |
442 | minimum. The ovs-ctl utility's "force-reload-kmod" function does all of the | |
443 | above, but also replaces the old kernel module with the new one. Open vSwitch | |
444 | startup scripts for Debian, XenServer and RHEL use ovs-ctl's functions and it | |
445 | is recommended that these functions be used for other software platforms too. | |
446 | ||
e3c7ed29 BP |
447 | Testsuites |
448 | ========== | |
449 | ||
450 | This section describe Open vSwitch's built-in support for various test | |
e9e85443 | 451 | suites. You must bootstrap, configure and build Open vSwitch (steps are |
e3c7ed29 BP |
452 | in "Building and Installing Open vSwitch for Linux, FreeBSD or NetBSD" |
453 | above) before you run the tests described here. You do not need to | |
454 | install Open vSwitch or to build or load the kernel module to run | |
455 | these test suites. You do not need supervisor privilege to run these | |
456 | test suites. | |
875ef81b | 457 | |
e3c7ed29 BP |
458 | Self-Tests |
459 | ---------- | |
460 | ||
461 | Open vSwitch includes a suite of self-tests. Before you submit patches | |
875ef81b KM |
462 | upstream, we advise that you run the tests and ensure that they pass. |
463 | If you add new features to Open vSwitch, then adding tests for those | |
464 | features will ensure your features don't break as developers modify | |
465 | other areas of Open vSwitch. | |
466 | ||
e3c7ed29 | 467 | Refer to "Testsuites" above for prerequisites. |
875ef81b KM |
468 | |
469 | To run all the unit tests in Open vSwitch, one at a time: | |
542cc9bb | 470 | `make check` |
875ef81b KM |
471 | This takes under 5 minutes on a modern desktop system. |
472 | ||
473 | To run all the unit tests in Open vSwitch, up to 8 in parallel: | |
542cc9bb | 474 | `make check TESTSUITEFLAGS=-j8` |
875ef81b KM |
475 | This takes under a minute on a modern 4-core desktop system. |
476 | ||
477 | To see a list of all the available tests, run: | |
542cc9bb | 478 | `make check TESTSUITEFLAGS=--list` |
875ef81b KM |
479 | |
480 | To run only a subset of tests, e.g. test 123 and tests 477 through 484: | |
542cc9bb | 481 | `make check TESTSUITEFLAGS='123 477-484'` |
875ef81b KM |
482 | (Tests do not have inter-dependencies, so you may run any subset.) |
483 | ||
484 | To run tests matching a keyword, e.g. "ovsdb": | |
542cc9bb | 485 | `make check TESTSUITEFLAGS='-k ovsdb'` |
875ef81b KM |
486 | |
487 | To see a complete list of test options: | |
542cc9bb | 488 | `make check TESTSUITEFLAGS=--help` |
875ef81b KM |
489 | |
490 | The results of a testing run are reported in tests/testsuite.log. | |
491 | Please report test failures as bugs and include the testsuite.log in | |
492 | your report. | |
493 | ||
27de40d0 LR |
494 | If the build was configured with "--enable-coverage" and the "lcov" |
495 | utility is installed, you can run the testsuite and generate a code | |
496 | coverage report by using "make check-lcov". All of the options for | |
497 | TESTSUITEFLAGS are available, so you can e.g.: | |
498 | `make check-lcov TESTSUITEFLAGS=-j8 -k ovn` | |
499 | ||
875ef81b KM |
500 | If you have "valgrind" installed, then you can also run the testsuite |
501 | under valgrind by using "make check-valgrind" in place of "make | |
502 | check". All the same options are available via TESTSUITEFLAGS. When | |
542cc9bb TG |
503 | you do this, the "valgrind" results for test `<N>` are reported in files |
504 | named `tests/testsuite.dir/<N>/valgrind.*`. You may find that the | |
875ef81b | 505 | valgrind results are easier to interpret if you put "-q" in |
447fe5cf | 506 | ~/.valgrindrc, since that reduces the amount of output. |
875ef81b KM |
507 | |
508 | Sometimes a few tests may fail on some runs but not others. This is | |
509 | usually a bug in the testsuite, not a bug in Open vSwitch itself. If | |
510 | you find that a test fails intermittently, please report it, since the | |
0d3f2152 BP |
511 | developers may not have noticed. You can make the testsuite |
512 | automatically rerun tests that fail, by adding RECHECK=yes to the | |
513 | "make" command line, e.g.: | |
514 | `make check TESTSUITEFLAGS=-j8 RECHECK=yes` | |
875ef81b | 515 | |
e3c7ed29 BP |
516 | OFTest |
517 | ------ | |
518 | ||
519 | OFTest is an OpenFlow protocol testing suite. Open vSwitch includes a | |
520 | Makefile target to run OFTest with Open vSwitch in "dummy mode". In | |
521 | this mode of testing, no packets travel across physical or virtual | |
522 | networks. Instead, Unix domain sockets stand in as simulated | |
523 | networks. This simulation is imperfect, but it is much easier to set | |
524 | up, does not require extra physical or virtual hardware, and does not | |
525 | require supervisor privileges. | |
526 | ||
527 | To run OFTest with Open vSwitch, first read and follow the | |
528 | instructions under "Testsuites" above. Second, obtain a copy of | |
529 | OFTest and install its prerequisites. You need a copy of OFTest that | |
530 | includes commit 406614846c5 (make ovs-dummy platform work again). | |
531 | This commit was merged into the OFTest repository on Feb 1, 2013, so | |
532 | any copy of OFTest more recent than that should work. Testing OVS in | |
533 | dummy mode does not require root privilege, so you may ignore that | |
534 | requirement. | |
535 | ||
536 | Optionally, add the top-level OFTest directory (containing the "oft" | |
537 | program) to your $PATH. This slightly simplifies running OFTest later. | |
538 | ||
539 | To run OFTest in dummy mode, run the following command from your Open | |
540 | vSwitch build directory: | |
542cc9bb TG |
541 | `make check-oftest OFT=<oft-binary>` |
542 | where `<oft-binary>` is the absolute path to the "oft" program in | |
e3c7ed29 BP |
543 | OFTest. |
544 | ||
545 | If you added "oft" to your $PATH, you may omit the OFT variable | |
546 | assignment: | |
542cc9bb | 547 | `make check-oftest` |
e3c7ed29 BP |
548 | By default, "check-oftest" passes "oft" just enough options to enable |
549 | dummy mode. You can use OFTFLAGS to pass additional options. For | |
550 | example, to run just the basic.Echo test instead of all tests (the | |
551 | default) and enable verbose logging: | |
542cc9bb | 552 | `make check-oftest OFT=<oft-binary> OFTFLAGS='--verbose -T basic.Echo'` |
e3c7ed29 BP |
553 | |
554 | If you use OFTest that does not include commit 4d1f3eb2c792 (oft: | |
555 | change default port to 6653), merged into the OFTest repository in | |
556 | October 2013, then you need to add an option to use the IETF-assigned | |
557 | controller port: | |
542cc9bb | 558 | `make check-oftest OFT=<oft-binary> OFTFLAGS='--port=6653'` |
e3c7ed29 BP |
559 | |
560 | Please interpret OFTest results cautiously. Open vSwitch can fail a | |
561 | given test in OFTest for many reasons, including bugs in Open vSwitch, | |
562 | bugs in OFTest, bugs in the "dummy mode" integration, and differing | |
563 | interpretations of the OpenFlow standard and other standards. | |
564 | ||
565 | Open vSwitch has not been validated against OFTest. Please do report | |
566 | test failures that you believe to represent bugs in Open vSwitch. | |
567 | Include the precise versions of Open vSwitch and OFTest in your bug | |
568 | report, plus any other information needed to reproduce the problem. | |
569 | ||
570 | Ryu | |
571 | --- | |
572 | ||
573 | Ryu is an OpenFlow controller written in Python that includes an | |
574 | extensive OpenFlow testsuite. Open vSwitch includes a Makefile target | |
575 | to run Ryu in "dummy mode". See "OFTest" above for an explanation of | |
576 | dummy mode. | |
577 | ||
578 | To run Ryu tests with Open vSwitch, first read and follow the | |
579 | instructions under "Testsuites" above. Second, obtain a copy of Ryu, | |
580 | install its prerequisites, and build it. You do not need to install | |
581 | Ryu (some of the tests do not get installed, so it does not help). | |
582 | ||
583 | To run Ryu tests, run the following command from your Open vSwitch | |
584 | build directory: | |
542cc9bb TG |
585 | `make check-ryu RYUDIR=<ryu-source-dir>` |
586 | where `<ryu-source-dir>` is the absolute path to the root of the Ryu | |
587 | source distribution. The default `<ryu-source-dir>` is `$srcdir/../ryu` | |
e3c7ed29 | 588 | where $srcdir is your Open vSwitch source directory, so if this |
542cc9bb | 589 | default is correct then you make simply run `make check-ryu`. |
e3c7ed29 BP |
590 | |
591 | Open vSwitch has not been validated against Ryu. Please do report | |
592 | test failures that you believe to represent bugs in Open vSwitch. | |
593 | Include the precise versions of Open vSwitch and Ryu in your bug | |
594 | report, plus any other information needed to reproduce the problem. | |
595 | ||
1ce96d2a TG |
596 | Vagrant |
597 | ------- | |
598 | ||
b56b2566 | 599 | Requires: Vagrant (version 1.7.0 or later) and a compatible hypervisor |
1ce96d2a | 600 | |
e9e85443 FL |
601 | You must bootstrap and configure the sources (steps are in "Building |
602 | and Installing Open vSwitch for Linux, FreeBSD or NetBSD" above) before | |
603 | you run the steps described here. | |
604 | ||
1ce96d2a TG |
605 | A Vagrantfile is provided allowing to compile and provision the source |
606 | tree as found locally in a virtual machine using the following commands: | |
607 | ||
608 | vagrant up | |
609 | vagrant ssh | |
610 | ||
611 | This will bring up w Fedora 20 VM by default, alternatively the | |
b56b2566 AZ |
612 | `Vagrantfile` can be modified to use a different distribution box as |
613 | base. Also, the VM can be reprovisioned at any time: | |
1ce96d2a TG |
614 | |
615 | vagrant provision | |
616 | ||
b56b2566 AZ |
617 | OVS out-of-tree compilation environment can be set up with: |
618 | ||
619 | ./boot.sh | |
620 | vagrant provision --provision-with configure_ovs,build_ovs | |
621 | ||
622 | This will set up an out-of-tree build environment in /home/vagrant/build. | |
623 | The source code can be found in /vagrant. Out-of-tree build is preferred | |
624 | to work around limitations of the sync file systems. | |
625 | ||
626 | To recompile and reinstall OVS using RPM: | |
627 | ||
628 | ./boot.sh | |
629 | vagrant provision --provision-with configure_ovs,install_rpm | |
630 | ||
548f9fe7 DDP |
631 | Two provisioners are included to run system tests with the OVS kernel |
632 | module or with a userspace datapath. This tests are different from | |
633 | the self-tests mentioned above. To run them: | |
634 | ||
635 | ./boot.sh | |
636 | vagrant provision --provision-with configure_ovs,test_ovs_kmod,test_ovs_system_userspace | |
637 | ||
8187f55b TG |
638 | Continuous Integration with Travis-CI |
639 | ------------------------------------- | |
640 | ||
641 | A .travis.yml file is provided to automatically build Open vSwitch with | |
642 | various build configurations and run the testsuite using travis-ci. | |
643 | Builds will be performed with gcc, sparse and clang with the -Werror | |
644 | compiler flag included, therefore the build will fail if a new warning | |
645 | has been introduced. | |
646 | ||
647 | The CI build is triggered via git push (regardless of the specific | |
648 | branch) or pull request against any Open vSwitch GitHub repository that | |
649 | is linked to travis-ci. | |
650 | ||
651 | Instructions to setup travis-ci for your GitHub repository: | |
652 | ||
35ab726f | 653 | 1. Go to http://travis-ci.org/ and sign in using your GitHub ID. |
8187f55b TG |
654 | 2. Go to the "Repositories" tab and enable the ovs repository. You |
655 | may disable builds for pushes or pull requests. | |
656 | 3. In order to avoid forks sending build failures to the upstream | |
657 | mailing list, the notification email recipient is encrypted. If you | |
658 | want to receive email notification for build failures, replace the | |
659 | the encrypted string: | |
660 | 3.1) Install the travis-ci CLI (Requires ruby >=2.0): | |
661 | gem install travis | |
662 | 3.2) In your Open vSwitch repository: | |
663 | travis encrypt mylist@mydomain.org | |
664 | 3.3) Add/replace the notifications section in .travis.yml and fill | |
665 | in the secure string as returned by travis encrypt: | |
666 | ||
667 | notifications: | |
668 | email: | |
669 | recipients: | |
670 | - secure: "....." | |
671 | ||
672 | (You may remove/omit the notifications section to fall back to | |
673 | default notification behaviour which is to send an email directly | |
674 | to the author and committer of the failing commit. Note that the | |
675 | email is only sent if the author/committer have commit rights for | |
676 | the particular GitHub repository). | |
677 | ||
678 | 4. Pushing a commit to the repository which breaks the build or the | |
679 | testsuite will now trigger a email sent to mylist@mydomain.org | |
680 | ||
4b11d5e8 | 681 | Bug Reporting |
e3c7ed29 | 682 | ============= |
4b11d5e8 | 683 | |
37ea6436 | 684 | Please report problems to bugs@openvswitch.org. |
9feb1017 TG |
685 | |
686 | [README.md]:README.md | |
687 | [INSTALL.Debian.md]:INSTALL.Debian.md | |
688 | [INSTALL.Fedora.md]:INSTALL.Fedora.md | |
689 | [INSTALL.RHEL.md]:INSTALL.RHEL.md | |
690 | [INSTALL.XenServer.md]:INSTALL.XenServer.md | |
691 | [INSTALL.NetBSD.md]:INSTALL.NetBSD.md | |
692 | [INSTALL.DPDK.md]:INSTALL.DPDK.md | |
693 | [INSTALL.userspace.md]:INSTALL.userspace.md | |
694 | [FAQ.md]:FAQ.md |