1 Installation Instructions for OpenFlow Reference Release
3 This document describes how to build, install, and execute the
4 reference implementation of OpenFlow. Please send any comments to:
6 <info@openflowswitch.org>
11 There are two principal ways to build and install this distribution:
13 - Using "configure" and "make" in the ordinary way. See
14 Building Conventionally below for detailed instructions.
16 - As a set of Debian packages. Refer to Building Debian
17 Packages, below, for instructions.
22 Regardless of how it is built, OpenFlow has a common set of
23 prerequisites. To compile the userspace programs in the OpenFlow
24 reference distribution, you will need the following software:
26 - A make program, e.g. GNU make
27 (http://www.gnu.org/software/make/). BSD make should also work.
29 - The GNU C compiler (http://gcc.gnu.org/). We generally test
30 with version 4.1 or 4.2.
32 - libssl, from OpenSSL (http://www.openssl.org/), is optional but
33 recommended. libssl is required to establish confidentiality
34 and authenticity in the connections among OpenFlow switches and
35 controllers. To enable, configure with --enable-ssl=yes
37 If you are working from a Git tree or snapshot (instead of from a
38 distribution tarball), or if you modify the OpenFlow build system, you
39 will also need the following software:
41 - Autoconf version 2.59 or later (http://www.gnu.org/software/autoconf).
43 - Automake version 1.10 or later (http://www.gnu.org/software/automake).
45 - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
51 To build Debian packages from the OpenFlow distribution, you will need
52 to install a number of Debian packages in addition to the base
53 prerequisites listed above. These additional prerequisites may be
54 found listed as "Build-Depends" in debian/control in the source tree.
55 To check that they are installed, first install the dpkg-dev package,
56 then run dpkg-checkbuilddeps from the top level of the OpenFlow source
59 To build Debian packages without being root, also install the
62 Kernel-Based Switch Prerequisites
63 ---------------------------------
65 The OpenFlow distribution also includes a Linux kernel module that can
66 be used to achieve higher switching performance. To compile the
67 kernel module, you must install the following in addition to the
68 software listed in the "Base Prerequisites" section above:
70 - A supported Linux kernel version. Please refer to README for a
71 list of supported versions.
73 The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
74 to be built as a kernel module. (This is common in kernels
75 provided by Linux distributions.) The bridge module must not be
76 loaded or in use. If the bridge module is running (check with
77 "lsmod | grep bridge"), you must remove it ("rmmod bridge")
78 before starting the datapath.
80 - The correct version of GCC for the kernel that you are building
83 * To build a kernel module for a Linux 2.6 kernel, you need
84 the same version of GCC that was used to build that kernel
85 (usually version 4.0 or later).
87 * To build a kernel module for a Linux 2.4 kernel, you need an
88 earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
90 - A kernel build directory corresponding to the Linux kernel image
91 the module is to run on. Under Debian and Ubuntu, for example,
92 each linux-image package containing a kernel binary has a
93 corresponding linux-headers package with the required build
96 Building Conventionally
97 =======================
99 This section explains how to build and install the OpenFlow
100 distribution in the ordinary way using "configure" and "make".
102 0. Check that you have installed all the prerequisites listed above in
103 the Base Prerequisites section. If you want to compile the Linux
104 kernel module, also check that the prequisites listed under
105 Kernel-Based Switch Prequisites are installed.
107 1. In the top source directory, configure the package by running the
108 configure script. You can usually invoke configure without any
113 To use a specific C compiler for compiling OpenFlow user programs,
114 also specify it on the configure command line, like so:
116 % ./configure CC=gcc-4.2
118 To build the Linux kernel module, so that you can run the
119 kernel-based switch, add --with-l26 or --with-l24 option, or both,
120 to the configure script's command line. Refer to Building the
121 Linux Kernel-Based Switch, below, for more information.
123 The configure script accepts a number of other options and honors
124 additional environment variables. For a full list, invoke
125 configure with the --help option.
127 2. Run make in the top source directory:
131 The following binaries will be built:
133 - Switch executable: switch/switch. This executable is built
134 only if the configure script detects a supported interface to
135 network devices. Refer to README for a list of OSes whose
136 network device interfaces are supported.
138 - Secure channel executable: secchan/secchan.
140 - Controller executable: controller/controller.
142 - Datapath administration utility: utilities/dpctl.
144 - Runtime logging configuration utility: utilities/vlogconf.
146 If you passed --with-l26 to configure, "make" will also build the
147 following kernel modules:
149 - datapath/linux-2.6/openflow_mod.ko
151 - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
152 specified on --enable-hw-tables (if any).
154 If you passed --with-l24 to configure, "make" will also build the
155 following kernel modules:
157 - datapath/linux-2.4/openflow_mod.o
159 - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
160 specified on --enable-hw-tables (if any).
162 3. Run "make install" to install the executables and manpages into the
163 running system, by default under /usr/local.
165 4. If you built kernel modules, you may load them with "insmod", e.g.:
168 % insmod datapath/linux-2.6/openflow_mod.ko
171 % insmod datapath/linux-2.4/compat24_mod.o
172 % insmod datapath/linux-2.4/openflow_mod.o
174 After you load the openflow module, you may load one hardware switch
175 table module (if any were built) to enable support for that hardware
178 The insmod program must be run as root. You may need to specify a
179 full path to insmod, e.g. /sbin/insmod. To verify that the modules
180 have been loaded, run "/sbin/lsmod" and check that openflow_mod is
183 4. Test the userspace programs, as described under Testing Userspace
186 5. If you built the kernel module, test the kernel-based switch, as
187 described under Testing the Kernel-Based Implementation below.
189 Building the Linux Kernel-Based Switch
190 --------------------------------------
192 To build the kernel module, follow the build process described above,
193 but pass the location of the kernel build directory as an additional
194 argument to the configure script, as described under step 1 in that
195 section. Specify the location on --with-l26 for Linux 2.6, --with-l24
196 for Linux 2.4. For example, to build for a running instance of Linux
199 % ./configure --with-l26=/lib/modules/`uname -r`/build
201 To build for a running instance of Linux 2.4:
203 % ./configure --with-l24=/lib/modules/`uname -r`/build
205 If you wish to build OpenFlow for an architecture other than the
206 architecture used for compilation, you may specify the kernel
207 architecture string using the KARCH variable when invoking the
208 configure script. For example, to build OpenFlow for MIPS with Linux
211 % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
213 If you have hardware that supports accelerated OpenFlow switching, and
214 you have obtained a hardware table module for your hardware and
215 extracted it into the OpenFlow reference distribution source tree,
216 then you may also enable building support for the hardware switching
217 table with --enable-hw-tables. For example, if your hardware
218 switching table is in a directory named datapath/hwtable-foomatic, you
219 could compile support for it with the running Linux 2.6 kernel like
222 % ./configure --with-l26=/lib/modules/`uname -r`/build \
223 --enable-hw-tables=foomatic
225 For more information about hardware table modules, please read
226 README.hwtables at the root of the OpenFlow distribution tree.
228 Building Debian Packages
229 ========================
231 Follow these instructions to build Debian packages for OpenFlow.
233 0. Check that you have installed all the prerequisites listed above in
234 the Base Prerequisites and Debian Prerequisites sections above.
236 1. In the top source directory, run the following command, as root:
240 Alternatively, if you installed the "fakeroot" package, you may run
241 dpkg-buildpackage as an ordinary user with the following syntax:
243 % dpkg-buildpackage -rfakeroot
245 The following packages will be built in the directory above the
248 - openflow-controller: The OpenFlow controller. Depends on
249 openflow-pki (see below).
251 - openflow-switch: Install this package on a machine that acts
252 as an OpenFlow userspace or kernel switch.
254 - openflow-datapath-source: Source code for OpenFlow's Linux
257 - openflow-pki: Public-key infrastructure for OpenFlow. Install
258 this package on a machine that acts as an OpenFlow PKI server
259 (see "Establishing a Public Key Infrastructure" below).
261 - openflow-common: Files and utilities required by more than one
262 of the above packages.
264 2. To set up an OpenFlow controller, install the openflow-controller
265 package and its dependencies. You may configure it by editing
266 /etc/default/openflow-controller, e.g. to enable non-SSL
267 connections, which are disabled by default. If you change the
268 default settings, you will need to restart the controller by
271 % /etc/init.d/openflow-controller restart
273 3. To set up an OpenFlow switch, install the openflow-switch package
274 and its dependencies. If it is to be a kernel-based switch, also
275 install openflow-datapath-source, then follow the instructions in
276 /usr/share/doc/openflow-datapath-source/README.Debian to build and
277 install the kernel module.
279 You may configure the switch one of the following ways:
281 - Completely by hand, as described under the Testing section
284 For the userspace switch, this is the only supported form of
287 - By editing /etc/default/openflow-switch. You must at least
288 configure some network devices, by uncommenting NETDEVS and
289 adding the appropriate devices to the list, e.g. NETDEVS="eth0
292 After you edit this file, you will need to start the switch by
295 % /etc/init.d/openflow-switch restart
297 This form of configuration is not supported for the userspace
300 - By running the ofp-switch-setup program. This interactive
301 program will walk you through all the steps of configuring an
302 OpenFlow switch, including configuration of SSL certificates.
303 Run it without arguments, as root:
307 This form of configuration is not supported for the userspace
313 Testing Userspace Programs
314 --------------------------
316 0. The commands below must run as root, so log in as root, or use a
317 program such as "su" to become root temporarily.
319 1. Start the OpenFlow controller running in the background, by running
320 the "controller" program with a command like the following:
324 This command causes the controller to bind to port 975 (the
325 default) awaiting connections from OpenFlow switches. See
326 controller(8) for details.
328 2. On the same machine, use the "switch" program to start an OpenFlow
329 switch, specifying network devices to use as switch ports on the -i
330 option as a comma-separated list, like so:
332 # switch tcp:127.0.0.1 -i eth1,eth2
334 The network devices that you specify should not have configured IP
337 3. The controller causes each switch that connects to it to act like a
338 learning Ethernet switch. Thus, devices plugged into the specified
339 network ports should now be able to send packets to each other, as
340 if they were plugged into ports on a conventional Ethernet switch.
342 Troubleshooting: if the commands above do not work, try using the -v
343 or --verbose option on the controller or switch commands, which will
344 cause a large amount of debug output from each program.
346 Remote switches: These instructions assume that the controller and the
347 switch are running on the same machine. This is an easy configuration
348 for testing, but a more conventional setup would run a controller on
349 one machine and one or more switches on different machines. To do so,
350 simply specify the IP address of the controller as the first argument
351 to the switch program (in place of 127.0.0.1). (Note: The userspace
352 switch must be connected to the controller over a "control network"
353 that is physically separate from the one that the switch and
354 controller are controlling. The kernel-based switch does not have
357 Testing the Kernel-Based Implementation
358 ---------------------------------------
360 The OpenFlow kernel module must be loaded, as described in the
361 previous section, before it may be tested.
363 0. The commands below must run as root, so log in as root, or use a
364 program such as "su" to become root temporarily.
366 1. Create a datapath instance. The command below creates a datapath with
367 ID 0 (see dpctl(8) for more detailed usage information).
371 In principle, openflow_mod supports multiple datapaths within the
372 same host, but this is rarely useful in practice.
374 If you built a support module for hardware accelerated OpenFlow
375 switching and you want to use it, you must load it before creating
376 the datapath with "dpctl adddp".
378 2. Use dpctl to attach the datapath to physical interfaces on the
379 machine. Say, for example, you want to create a trivial 2-port
380 switch using interfaces eth1 and eth2, you would issue the following
386 You can verify that the interfaces were successfully added by asking
387 dpctl to print the current status of datapath 0:
391 3. (Optional) You can manually add flows to the datapath to test using
392 dpctl add-flows and view them using dpctl dump-flows. See dpctl(8)
395 4. The simplest way to test the datapath is to run the provided sample
396 controller on the host machine to manage the datapath directly using
401 Once the controller is running, the datapath should operate like a
402 learning Ethernet switch. You may monitor the flows in the datapath
403 flow table using "dpctl dump-flows" command.
405 The preceding instructions assume that the controller and the switch
406 are running on the same machine. This is an easy configuration for
407 testing, but a more conventional setup would run a controller on one
408 machine and one or more switches on different machines. Use the
409 following instructions to set up remote switches:
411 1. Start the datapath and attach it to two or more physical ports as
412 described in the previous section.
414 2. Run the controller in passive TCP mode on the host which will act as
415 the controller. In the example below, the controller will bind to
416 port 975 (the default) awaiting connections from secure channels.
418 # controller -v ptcp:
420 (See controller(8) for more details)
422 Make sure the machine hosting the controller is reachable by the switch.
424 3. Arrange so that the switch can reach the controller over the
425 network. There are two ways to do this:
427 - Use a "control network" that is completely separate from the
428 "data network" to be controlled ("out-of-band control"). To
429 do so, configure a network device (one that has not been added
430 to the datapath with "dpctl addif") to access the control
431 network in the usual way.
433 - Use the same network for control and for data ("in-band
434 control"). For this purpose, each datapath nl:K has a
435 corresponding virtual network device named ofK.
437 When in-band control is used, the location of the controller
438 may be configured manually or discovered automatically:
440 * Manual configuration: Start by bringing up of0 before
441 you start the secure channel:
445 Before the secure channel starts up, the of0 device
446 cannot send or receive any packets, so the next step
447 depends on whether connectivity is required to configure
448 the device's IP address:
450 . If the switch has a static IP address, you may
451 configure its IP address now, e.g.:
453 # ifconfig of0 192.168.1.1
455 . If the switch does not have a static IP address,
456 e.g. its IP address is obtained dynamically via
457 DHCP, then proceed to step 4. The DHCP client will
458 not be able to contact the DHCP server until the
459 secure channel has started up.
461 * Controller discovery: No special setup is required at
462 the switch, but you must specially configure a DHCP
463 server to give out the switch's IP address and to tell
464 it the location of the controller. See secchan(8) for
467 4. Run secchan on the datapath host to start the secure channel
468 connecting the datapath to a remote controller. (See secchan(8)
469 for usage details). The details depend on how you configured the
472 - If you are using in-band control and controller discovery,
473 invoke secchan something like this:
477 The secure channel should connect to the controller after it
478 obtains its own IP address and the controller's location via
479 DHCP. This can take a few seconds. Switch setup is now
482 - Otherwise, the secure channel should be configured to connect
483 to the controller's IP address on the port configured in step
484 2. If the controller is running on host 192.168.1.2 port 975
485 (the default port) and the datapath ID is 0, the secchan
486 invocation would look like:
488 # secchan -v nl:0 tcp:192.168.1.2
490 If you are using out-of-band control, or if you are using
491 in-band control and the switch has a static IP address, the
492 secure channel should quickly connect to the controller.
493 Setup is now complete. Otherwise, proceed to step 5.
495 5. If you are using the same network for control and data, and the
496 switch obtains its IP address dynamically, then you may now obtain
497 the switch's IP address, e.g. by invoking a DHCP client. The
498 secure channel will only be able to connect to the controller after
499 an IP address has been obtained.
504 Secure operation over SSL
505 -------------------------
507 The instructions above set up OpenFlow for operation over a plaintext
508 TCP connection. Production use of OpenFlow should use SSL[*] to
509 ensure confidentiality and authenticity of traffic among switches and
510 controllers. The source must be configured with --enable-ssl=yes to
511 build with SSL support.
513 To use SSL with OpenFlow, you must set up a public-key infrastructure
514 (PKI) including a pair of certificate authorities (CAs), one for
515 controllers and one for switches. If you have an established PKI,
516 OpenFlow can use it directly. Otherwise, refer to "Establishing a
517 Public Key Infrastructure" below.
519 To configure the controller to listen for SSL connections on port 976
520 (the default), invoke it as follows:
522 # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
525 where PRIVKEY is a file containing the controller's private key, CERT
526 is a file containing the controller CA's certificate for the
527 controller's public key, and CACERT is a file containing the root
528 certificate for the switch CA. If, for example, your PKI was created
529 with the instructions below, then the invocation would look like:
531 # controller -v pssl: --private-key=ctl-privkey.pem \
532 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
534 To configure a switch to connect to a controller running on port 976
535 (the default) on host 192.168.1.2 over SSL, invoke it as follows:
537 # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \
538 --certificate=CERT --ca-cert=CACERT
540 where INTERFACES is the command-separated list of network device
541 interfaces, PRIVKEY is a file containing the switch's private key,
542 CERT is a file containing the switch CA's certificate for the switch's
543 public key, and CACERT is a file containing the root certificate for
544 the controller CA. If, for example, your PKI was created with the
545 instructions below, then the invocation would look like:
547 # secchan -v -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \
548 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
550 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
551 specified by RFC 2246, which is very similar to SSL version 3.0.
552 TLSv1 was released in January 1999, so all current software and
553 hardware should implement it.
555 Establishing a Public Key Infrastructure
556 ----------------------------------------
558 If you do not have a PKI, the ofp-pki script included with OpenFlow
559 can help. To create an initial PKI structure, invoke it as:
561 which will create and populate a new directory named "pki" under the
564 The pki directory contains two important subdirectories. The
565 controllerca subdirectory contains controller certificate authority
566 related files, including the following:
568 - cacert.pem: Root certificate for the controller certificate
569 authority. This file must be provided to the switch or secchan
570 program with the --ca-cert option to enable it to authenticate
573 - private/cakey.pem: Private signing key for the controller
574 certificate authority. This file must be kept secret. There is
575 no need for switches or controllers to have a copy of it.
577 The switchca subdirectory contains switch certificate authority
578 related files, analogous to those in the controllerca subdirectory:
580 - cacert.pem: Root certificate for the switch certificate
581 authority. This file must be provided to the controller program
582 with the --ca-cert option to enable it to authenticate valid
585 - private/cakey.pem: Private signing key for the switch
586 certificate authority. This file must be kept secret. There is
587 no need for switches or controllers to have a copy of it.
589 After you create the initial structure, you can create keys and
590 certificates for switches and controllers with ofp-pki. To create a
591 controller private key and certificate in files named ctl-privkey.pem
592 and ctl-cert.pem, for example, you could run:
593 % ofp-pki req+sign ctl controller
594 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
595 controller for its use at runtime (they could then be deleted from
596 their original locations). The --private-key and --certificate
597 options of controller, respectively, would point to these files.
599 Analogously, to create a switch private key and certificate in files
600 named sc-privkey.pem and sc-cert.pem, for example, you could run:
601 % ofp-pki req+sign sc switch
602 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
603 for its use at runtime (they could then be deleted from their original
604 locations). The --private-key and --certificate options,
605 respectively, of switch and secchan would point to these files.
610 Please report problems to:
611 info@openflowswitch.org