1 Open vSwitch Installation Instructions
3 This document describes how to build, install, and execute
6 Open vSwitch implements an Ethernet switch with MAC learning that may
7 be configured with any of the following features:
9 * NIC bonding with automatic fail-over and source MAC-based TX
10 load balancing ("SLB").
12 * 802.1Q VLAN support.
14 * Port mirroring, with optional VLAN tagging.
16 * NetFlow v5 flow logging.
18 * Connectivity to an external OpenFlow controller, such as
21 The current version of this distribution requires a kernel module to
22 be built and loaded. An (optional) entirely userspace switch is on
23 the roadmap for future versions.
25 The distribution also contains a number of related utilities.
30 There are two principal ways to build and install this distribution:
32 - Using "configure" and "make" in the ordinary way. See
33 Building Conventionally below for detailed instructions.
35 - As a set of Debian packages. Refer to Building Debian
36 Packages, below, for instructions.
41 Regardless of how it is built, Open vSwitch has a common set of
42 prerequisites. To compile the userspace programs in the OpenFlow
43 reference distribution, you will need the following software:
45 - A make program, e.g. GNU make
46 (http://www.gnu.org/software/make/). BSD make should also work.
48 - The GNU C compiler (http://gcc.gnu.org/). We generally test
49 with version 4.2 or 4.3.
51 - libssl, from OpenSSL (http://www.openssl.org/), is optional but
52 recommended if you plan to connect the Open vSwitch to an
53 OpenFlow controller. libssl is required to establish
54 confidentiality and authenticity in the connections from an
55 Open vSwitch to an OpenFlow controller. To enable, configure
56 with --enable-ssl=yes.
58 To compile the kernel module, you must also install the following:
60 - A supported Linux kernel version. Please refer to README for a
61 list of supported versions.
63 The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
64 to be built as a kernel module. (This is common in kernels
65 provided by Linux distributions.) The bridge module must not be
66 loaded or in use. If the bridge module is running (check with
67 "lsmod | grep bridge"), you must remove it ("rmmod bridge")
68 before starting the datapath.
70 - To build a kernel module, you need the same version of GCC that
71 was used to build that kernel (usually version 4.0 or later).
73 - A kernel build directory corresponding to the Linux kernel image
74 the module is to run on. Under Debian and Ubuntu, for example,
75 each linux-image package containing a kernel binary has a
76 corresponding linux-headers package with the required build
79 If you are working from a Git tree or snapshot (instead of from a
80 distribution tarball), or if you modify the Open vSwitch build system,
81 you will also need the following software:
83 - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
85 - Automake version 1.10 or later (http://www.gnu.org/software/automake).
87 - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
93 To build Debian packages from the Open vSwitch distribution, you will
94 need to install a number of Debian packages in addition to the base
95 prerequisites listed above. These additional prerequisites may be
96 found listed as "Build-Depends" in debian/control in the source tree.
97 To check that they are installed, first install the dpkg-dev package,
98 then run dpkg-checkbuilddeps from the top level of the OpenFlow source
101 To build Debian packages without being root, also install the
104 Building Conventionally
105 =======================
107 This section explains how to build and install the Open vSwitch
108 distribution in the ordinary way using "configure" and "make".
110 0. Check that you have installed all the prerequisites listed above in
111 the Base Prerequisites section.
113 1. In the top source directory, configure the package by running the
114 configure script. You can usually invoke configure without any
119 To use a specific C compiler for compiling OpenFlow user programs,
120 also specify it on the configure command line, like so:
122 % ./configure CC=gcc-4.2
124 To build the Linux kernel module, so that you can run the
125 kernel-based switch, pass the location of the kernel build
126 directory on --with-l26. For example, to build for a running
127 instance of Linux 2.6:
129 % ./configure --with-l26=/lib/modules/`uname -r`/build
131 If you wish to build the kernel module for an architecture other
132 than the architecture of the machine used for the build, you may
133 specify the kernel architecture string using the KARCH variable
134 when invoking the configure script. For example, to build for MIPS
137 % ./configure --with-l26=/path/to/linux-2.6 KARCH=mips
139 The configure script accepts a number of other options and honors
140 additional environment variables. For a full list, invoke
141 configure with the --help option.
143 2. Run make in the top source directory:
147 The following main binaries will be built:
149 - Virtual switch daemon: vswitchd/ovs-vswitchd
151 - Bridge compatibility daemon: vswitchd/ovs-brcompatd
153 - Datapath administration utility: utilities/ovs-dpctl.
155 Some less important binaries will be built also:
157 - Runtime configuration utility: utilities/ovs-appctl.
159 - Simple OpenFlow controller: utilities/ovs-controller.
161 - Secure channel executable: secchan/secchan.
163 - Miscellaneous utilities: utilities/ovs-discover,
166 - ANSI terminal support for EZIO 16x2 LCD panel:
167 extras/ezio/ezio-term (only if the proper libraries are
170 - Switch monitoring UI for small text displays:
171 extras/ezio/ovs-switchui (only if the proper libraries are
174 - Tests: various binaries in tests/.
176 If you passed --with-l26 to configure, "make" will also build the
177 following kernel modules:
179 - datapath/linux-2.6/brcompat_mod.ko
181 - datapath/linux-2.6/openflow_mod.ko
183 3. Run "make install" to install the executables and manpages into the
184 running system, by default under /usr/local.
186 4. If you built kernel modules, you may load them with "insmod", e.g.:
188 % insmod datapath/linux-2.6/openflow_mod.ko
190 The insmod program must be run as root. You may need to specify a
191 full path to insmod, e.g. /sbin/insmod. To verify that the modules
192 have been loaded, run "/sbin/lsmod" and check that openflow_mod is
195 5. Test the virtuaal switch, as described under Testing the Virtual
198 Building Debian Packages
199 ========================
201 Follow these instructions to build Debian packages for OpenFlow.
203 0. Check that you have installed all the prerequisites listed above in
204 the Base Prerequisites and Debian Prerequisites sections above.
206 1. In the top source directory, run the following command, as root:
210 Alternatively, if you installed the "fakeroot" package, you may run
211 dpkg-buildpackage as an ordinary user with the following syntax:
213 % dpkg-buildpackage -rfakeroot
215 The following packages will be built in the directory above the
218 - openflow-controller: The OpenFlow controller. Depends on
219 openflow-pki (see below).
221 - openflow-switch: Install this package on a machine that acts
222 as an OpenFlow kernel switch.
224 - openflow-datapath-source: Source code for OpenFlow's Linux
227 - openflow-pki: Public-key infrastructure for OpenFlow. Install
228 this package on a machine that acts as an OpenFlow PKI server
229 (see "Establishing a Public Key Infrastructure" below).
231 - openflow-common: Files and utilities required by more than one
232 of the above packages.
234 2. To set up an OpenFlow controller, install the openflow-controller
235 package and its dependencies. You may configure it by editing
236 /etc/default/openflow-controller, e.g. to enable non-SSL
237 connections, which are disabled by default. If you change the
238 default settings, you will need to restart the controller by
241 % /etc/init.d/openflow-controller restart
243 3. To set up an OpenFlow switch, install the openflow-switch package
244 and its dependencies. If it is to be a kernel-based switch, also
245 install openflow-datapath-source, then follow the instructions in
246 /usr/share/doc/openflow-datapath-source/README.Debian to build and
247 install the kernel module.
249 You may configure the switch one of the following ways:
251 - Completely by hand, as described under the Testing section
254 For the userspace datapath-based switch, this is the only
255 supported form of configuration.
257 - By editing /etc/default/openflow-switch. You must at least
258 configure some network devices, by uncommenting NETDEVS and
259 adding the appropriate devices to the list, e.g. NETDEVS="eth0
262 After you edit this file, you will need to start the switch by
265 % /etc/init.d/openflow-switch restart
267 This form of configuration is not supported for the userspace
268 datapath-based switch.
270 - By running the ovs-switch-setup program. This interactive
271 program will walk you through all the steps of configuring an
272 OpenFlow switch, including configuration of SSL certificates.
273 Run it without arguments, as root:
277 This form of configuration is not supported for the userspace
278 datapath-based switch.
283 This section explains how to install Open vSwitch in a network with one
284 controller and one or more switches, each of which runs on a separate
285 machine. Before you begin, you must decide on one of two ways for
286 each switch to reach the controller over the network:
288 - Use a "control network" that is completely separate from the
289 "data network" to be controlled ("out-of-band control"). The
290 location of the controller must be configured manually in this
293 - Use the same network for control and for data ("in-band
294 control"). When in-band control is used, the location of the
295 controller may be configured manually or discovered
296 automatically. We will assume manual configuration here;
297 please refer to secchan(8) for instructions on setting up
298 controller discovery.
303 On the machine that is to be the OpenFlow controller, start the
304 "ovs-controller" program listening for connections from switches on
305 TCP port 6633 (the default), as shown below.
307 # ovs-controller -v ptcp:
309 (See ovs-controller(8) for more details)
311 Make sure the machine hosting the controller is reachable by the
314 Testing the Virtual Switch
315 --------------------------
317 The Open vSwitch kernel module must be loaded, as described under
318 "Building Conventionally", before it may be used.
320 0. The commands below must run as root, so log in as root, or use a
321 program such as "su" to become root temporarily.
323 1. Create a datapath instance. The command below creates a datapath
324 identified as dp0 (see ovs-dpctl(8) for more detailed usage
327 # ovs-dpctl add-dp dp0
329 (dp0 is the first datapath within a host. openvswitch_mod supports
330 multiple datapaths within the same host, which would be identified
333 Creating datapath dp0 creates a new network device, also named dp0.
334 This network device, called the datapath's "local port", will be
335 bridged to the physical switch ports by the secchan, for use in
338 2. Use ovs-dpctl to attach the datapath to physical interfaces on the
339 machine. Say, for example, you want to create a trivial 2-port
340 switch using interfaces eth1 and eth2, you would issue the
343 # ovs-dpctl add-if dp0 eth1
344 # ovs-dpctl add-if dp0 eth2
346 You can verify that the interfaces were successfully added by asking
347 ovs-dpctl to print the current status of datapath dp0:
351 3. Arrange so that the switch can reach the controller over the
354 - If you are using out-of-band control, at this point make sure
355 that the switch machine can reach the controller over the
358 - If you are using in-band control, then at this point you must
359 configure the dp0 network device created in step 1. This
360 device is not yet bridged to any physical network (because
361 secchan does that, and it is not yet running), so the next
362 step depends on whether connectivity is required to configure
363 the device's IP address:
365 * If the switch has a static IP address, you may configure
366 its IP address now, e.g.:
368 # ifconfig dp0 192.168.1.1
370 * If the switch does not have a static IP address, e.g. its
371 IP address is obtained dynamically via DHCP, then proceed
372 to step 4. The DHCP client will not be able to contact
373 the DHCP server until the secure channel has started up.
375 - If you are using in-band control with controller discovery, no
376 configuration is required at this point. You may proceed to
379 4. Run secchan to start the secure channel connecting the datapath to
380 a remote controller. If the controller is running on host
381 192.168.1.2 port 6633 (the default port), the secchan invocation
382 would look like this:
384 # secchan dp0 tcp:192.168.1.2
386 - If you are using in-band control with controller discovery, omit
387 the second argument to the secchan command.
389 - If you are using out-of-band control, add --out-of-band to the
392 5. If you are using in-band control with manual configuration, and the
393 switch obtains its IP address dynamically, then you may now obtain
394 the switch's IP address, e.g. by invoking a DHCP client. The
395 secure channel will only be able to connect to the controller after
396 an IP address has been obtained.
398 6. The secure channel should connect to the controller within a few
399 seconds. It may take a little longer if controller discovery is in
400 use, because the switch must then also obtain its own IP address
401 and the controller's location via DHCP.
406 Secure operation over SSL
407 -------------------------
409 The instructions above set up Open vSwitch for operation over a
410 plaintext TCP connection. Production use of Open vSwitch should use
411 SSL[*] to ensure confidentiality and authenticity of traffic among
412 switches and controllers. The source must be configured with
413 --enable-ssl=yes to build with SSL support.
415 To use SSL with Open vSwitch, you must set up a public-key infrastructure
416 (PKI) including a pair of certificate authorities (CAs), one for
417 controllers and one for switches. If you have an established PKI,
418 Open vSwitch can use it directly. Otherwise, refer to "Establishing a
419 Public Key Infrastructure" below.
421 To configure the controller to listen for SSL connections on port 6633
422 (the default), invoke it as follows:
424 # ovs-controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
427 where PRIVKEY is a file containing the controller's private key, CERT
428 is a file containing the controller CA's certificate for the
429 controller's public key, and CACERT is a file containing the root
430 certificate for the switch CA. If, for example, your PKI was created
431 with the instructions below, then the invocation would look like:
433 # ovs-controller -v pssl: --private-key=ctl-privkey.pem \
434 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
436 To configure a switch to connect to a controller running on port 6633
437 (the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
439 # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
440 --certificate=CERT --ca-cert=CACERT
442 where DATAPATH is the datapath to connect to (e.g. dp0 or
443 unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
444 private key, CERT is a file containing the switch CA's certificate for
445 the switch's public key, and CACERT is a file containing the root
446 certificate for the controller CA. If, for example, your PKI was
447 created with the instructions below, then the invocation would look
450 # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
451 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
453 [*] To be specific, Open vSwitch uses TLS version 1.0 or later (TLSv1), as
454 specified by RFC 2246, which is very similar to SSL version 3.0.
455 TLSv1 was released in January 1999, so all current software and
456 hardware should implement it.
458 Establishing a Public Key Infrastructure
459 ----------------------------------------
461 If you do not have a PKI, the ovs-pki script included with Open vSwitch
462 can help. To create an initial PKI structure, invoke it as:
464 which will create and populate a new PKI directory. The default
465 location for the PKI directory depends on how the Open vSwitch tree was
466 configured (to see the configured default, look for the --dir option
467 description in the output of "ovs-pki --help").
469 The pki directory contains two important subdirectories. The
470 controllerca subdirectory contains controller certificate authority
471 related files, including the following:
473 - cacert.pem: Root certificate for the controller certificate
474 authority. This file must be provided to secchan with the
475 --ca-cert option to enable it to authenticate valid controllers.
477 - private/cakey.pem: Private signing key for the controller
478 certificate authority. This file must be kept secret. There is
479 no need for switches or controllers to have a copy of it.
481 The switchca subdirectory contains switch certificate authority
482 related files, analogous to those in the controllerca subdirectory:
484 - cacert.pem: Root certificate for the switch certificate
485 authority. This file must be provided to the controller program
486 with the --ca-cert option to enable it to authenticate valid
489 - private/cakey.pem: Private signing key for the switch
490 certificate authority. This file must be kept secret. There is
491 no need for switches or controllers to have a copy of it.
493 After you create the initial structure, you can create keys and
494 certificates for switches and controllers with ovs-pki. To create a
495 controller private key and certificate in files named ctl-privkey.pem
496 and ctl-cert.pem, for example, you could run:
497 % ovs-pki req+sign ctl controller
498 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
499 controller for its use at runtime (they could then be deleted from
500 their original locations). The --private-key and --certificate
501 options of ovs-controller, respectively, would point to these files.
503 Analogously, to create a switch private key and certificate in files
504 named sc-privkey.pem and sc-cert.pem, for example, you could run:
505 % ovs-pki req+sign sc switch
506 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
507 for its use at runtime (they could then be deleted from their original
508 locations). The --private-key and --certificate options,
509 respectively, of secchan would point to these files.
514 Please report problems to ovs-bugs@openvswitch.org.