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