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 In kernels prior to 2.6.9, VLAN support (CONFIG_VLAN_8021Q) must
81 be compiled either directly or as a module. Failure to do this
82 will cause an error on module insertion due to the
83 "dev_change_flags" symbol being undefined.
85 - The correct version of GCC for the kernel that you are building
88 * To build a kernel module for a Linux 2.6 kernel, you need
89 the same version of GCC that was used to build that kernel
90 (usually version 4.0 or later).
92 * To build a kernel module for a Linux 2.4 kernel, you need an
93 earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
95 - A kernel build directory corresponding to the Linux kernel image
96 the module is to run on. Under Debian and Ubuntu, for example,
97 each linux-image package containing a kernel binary has a
98 corresponding linux-headers package with the required build
101 Building Conventionally
102 =======================
104 This section explains how to build and install the OpenFlow
105 distribution in the ordinary way using "configure" and "make".
107 0. Check that you have installed all the prerequisites listed above in
108 the Base Prerequisites section. If you want to compile the Linux
109 kernel module, also check that the prequisites listed under
110 Kernel-Based Switch Prequisites are installed.
112 1. In the top source directory, configure the package by running the
113 configure script. You can usually invoke configure without any
118 To use a specific C compiler for compiling OpenFlow user programs,
119 also specify it on the configure command line, like so:
121 % ./configure CC=gcc-4.2
123 To build the Linux kernel module, so that you can run the
124 kernel-based switch, add --with-l26 or --with-l24 option, or both,
125 to the configure script's command line. Refer to Building the
126 Linux Kernel-Based Switch, below, for more information.
128 The configure script accepts a number of other options and honors
129 additional environment variables. For a full list, invoke
130 configure with the --help option.
132 2. Run make in the top source directory:
136 The following binaries will be built:
138 - Switch executable: switch/switch. This executable is built
139 only if the configure script detects a supported interface to
140 network devices. Refer to README for a list of OSes whose
141 network device interfaces are supported.
143 - Secure channel executable: secchan/secchan.
145 - Controller executable: controller/controller.
147 - Datapath administration utility: utilities/dpctl.
149 - Runtime logging configuration utility: utilities/vlogconf.
151 If you passed --with-l26 to configure, "make" will also build the
152 following kernel modules:
154 - datapath/linux-2.6/openflow_mod.ko
156 - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
157 specified on --enable-hw-tables (if any).
159 If you passed --with-l24 to configure, "make" will also build the
160 following kernel modules:
162 - datapath/linux-2.4/openflow_mod.o
164 - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
165 specified on --enable-hw-tables (if any).
167 3. Run "make install" to install the executables and manpages into the
168 running system, by default under /usr/local.
170 4. If you built kernel modules, you may load them with "insmod", e.g.:
173 % insmod datapath/linux-2.6/openflow_mod.ko
176 % insmod datapath/linux-2.4/compat24_mod.o
177 % insmod datapath/linux-2.4/openflow_mod.o
179 After you load the openflow module, you may load one hardware switch
180 table module (if any were built) to enable support for that hardware
183 The insmod program must be run as root. You may need to specify a
184 full path to insmod, e.g. /sbin/insmod. To verify that the modules
185 have been loaded, run "/sbin/lsmod" and check that openflow_mod is
188 4. Test the userspace programs, as described under Testing Userspace
191 5. If you built the kernel module, test the kernel-based switch, as
192 described under Testing the Kernel-Based Implementation below.
194 Building the Linux Kernel-Based Switch
195 --------------------------------------
197 To build the kernel module, follow the build process described above,
198 but pass the location of the kernel build directory as an additional
199 argument to the configure script, as described under step 1 in that
200 section. Specify the location on --with-l26 for Linux 2.6, --with-l24
201 for Linux 2.4. For example, to build for a running instance of Linux
204 % ./configure --with-l26=/lib/modules/`uname -r`/build
206 To build for a running instance of Linux 2.4:
208 % ./configure --with-l24=/lib/modules/`uname -r`/build
210 If you wish to build OpenFlow for an architecture other than the
211 architecture used for compilation, you may specify the kernel
212 architecture string using the KARCH variable when invoking the
213 configure script. For example, to build OpenFlow for MIPS with Linux
216 % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
218 If you have hardware that supports accelerated OpenFlow switching, and
219 you have obtained a hardware table module for your hardware and
220 extracted it into the OpenFlow reference distribution source tree,
221 then you may also enable building support for the hardware switching
222 table with --enable-hw-tables. For example, if your hardware
223 switching table is in a directory named datapath/hwtable-foomatic, you
224 could compile support for it with the running Linux 2.6 kernel like
227 % ./configure --with-l26=/lib/modules/`uname -r`/build \
228 --enable-hw-tables=foomatic
230 For more information about hardware table modules, please read
231 README.hwtables at the root of the OpenFlow distribution tree.
233 Building Debian Packages
234 ========================
236 Follow these instructions to build Debian packages for OpenFlow.
238 0. Check that you have installed all the prerequisites listed above in
239 the Base Prerequisites and Debian Prerequisites sections above.
241 1. In the top source directory, run the following command, as root:
245 Alternatively, if you installed the "fakeroot" package, you may run
246 dpkg-buildpackage as an ordinary user with the following syntax:
248 % dpkg-buildpackage -rfakeroot
250 The following packages will be built in the directory above the
253 - openflow-controller: The OpenFlow controller. Depends on
254 openflow-pki (see below).
256 - openflow-switch: Install this package on a machine that acts
257 as an OpenFlow userspace or kernel switch.
259 - openflow-datapath-source: Source code for OpenFlow's Linux
262 - openflow-pki: Public-key infrastructure for OpenFlow. Install
263 this package on a machine that acts as an OpenFlow PKI server
264 (see "Establishing a Public Key Infrastructure" below).
266 - openflow-common: Files and utilities required by more than one
267 of the above packages.
269 2. To set up an OpenFlow controller, install the openflow-controller
270 package and its dependencies. You may configure it by editing
271 /etc/default/openflow-controller, e.g. to enable non-SSL
272 connections, which are disabled by default. If you change the
273 default settings, you will need to restart the controller by
276 % /etc/init.d/openflow-controller restart
278 3. To set up an OpenFlow switch, install the openflow-switch package
279 and its dependencies. If it is to be a kernel-based switch, also
280 install openflow-datapath-source, then follow the instructions in
281 /usr/share/doc/openflow-datapath-source/README.Debian to build and
282 install the kernel module.
284 You may configure the switch one of the following ways:
286 - Completely by hand, as described under the Testing section
289 For the userspace switch, this is the only supported form of
292 - By editing /etc/default/openflow-switch. You must at least
293 configure some network devices, by uncommenting NETDEVS and
294 adding the appropriate devices to the list, e.g. NETDEVS="eth0
297 After you edit this file, you will need to start the switch by
300 % /etc/init.d/openflow-switch restart
302 This form of configuration is not supported for the userspace
305 - By running the ofp-switch-setup program. This interactive
306 program will walk you through all the steps of configuring an
307 OpenFlow switch, including configuration of SSL certificates.
308 Run it without arguments, as root:
312 This form of configuration is not supported for the userspace
318 Testing Userspace Programs
319 --------------------------
321 0. The commands below must run as root, so log in as root, or use a
322 program such as "su" to become root temporarily.
324 1. Start the OpenFlow controller running in the background, by running
325 the "controller" program with a command like the following:
329 This command causes the controller to bind to port 975 (the
330 default) awaiting connections from OpenFlow switches. See
331 controller(8) for details.
333 2. On the same machine, use the "switch" program to start an OpenFlow
334 switch, specifying network devices to use as switch ports on the -i
335 option as a comma-separated list, like so:
337 # switch tcp:127.0.0.1 -i eth1,eth2
339 The network devices that you specify should not have configured IP
342 3. The controller causes each switch that connects to it to act like a
343 learning Ethernet switch. Thus, devices plugged into the specified
344 network ports should now be able to send packets to each other, as
345 if they were plugged into ports on a conventional Ethernet switch.
347 Troubleshooting: if the commands above do not work, try using the -v
348 or --verbose option on the controller or switch commands, which will
349 cause a large amount of debug output from each program.
351 Remote switches: These instructions assume that the controller and the
352 switch are running on the same machine. This is an easy configuration
353 for testing, but a more conventional setup would run a controller on
354 one machine and one or more switches on different machines. To do so,
355 simply specify the IP address of the controller as the first argument
356 to the switch program (in place of 127.0.0.1). (Note: The userspace
357 switch must be connected to the controller over a "control network"
358 that is physically separate from the one that the switch and
359 controller are controlling. The kernel-based switch does not have
362 Testing the Kernel-Based Implementation
363 ---------------------------------------
365 The OpenFlow kernel module must be loaded, as described in the
366 previous section, before it may be tested.
368 0. The commands below must run as root, so log in as root, or use a
369 program such as "su" to become root temporarily.
371 1. Create a datapath instance. The command below creates a datapath with
372 ID 0 (see dpctl(8) for more detailed usage information).
376 In principle, openflow_mod supports multiple datapaths within the
377 same host, but this is rarely useful in practice.
379 If you built a support module for hardware accelerated OpenFlow
380 switching and you want to use it, you must load it before creating
381 the datapath with "dpctl adddp".
383 2. Use dpctl to attach the datapath to physical interfaces on the
384 machine. Say, for example, you want to create a trivial 2-port
385 switch using interfaces eth1 and eth2, you would issue the following
391 You can verify that the interfaces were successfully added by asking
392 dpctl to print the current status of datapath 0:
396 3. (Optional) You can manually add flows to the datapath to test using
397 dpctl add-flows and view them using dpctl dump-flows. See dpctl(8)
400 4. The simplest way to test the datapath is to run the provided sample
401 controller on the host machine to manage the datapath directly using
406 Once the controller is running, the datapath should operate like a
407 learning Ethernet switch. You may monitor the flows in the datapath
408 flow table using "dpctl dump-flows" command.
410 The preceding instructions assume that the controller and the switch
411 are running on the same machine. This is an easy configuration for
412 testing, but a more conventional setup would run a controller on one
413 machine and one or more switches on different machines. Use the
414 following instructions to set up remote switches:
416 1. Start the datapath and attach it to two or more physical ports as
417 described in the previous section.
419 2. Run the controller in passive TCP mode on the host which will act as
420 the controller. In the example below, the controller will bind to
421 port 975 (the default) awaiting connections from secure channels.
423 # controller -v ptcp:
425 (See controller(8) for more details)
427 Make sure the machine hosting the controller is reachable by the switch.
429 3. Arrange so that the switch can reach the controller over the
430 network. There are two ways to do this:
432 - Use a "control network" that is completely separate from the
433 "data network" to be controlled ("out-of-band control"). To
434 do so, configure a network device (one that has not been added
435 to the datapath with "dpctl addif") to access the control
436 network in the usual way.
438 - Use the same network for control and for data ("in-band
439 control"). For this purpose, each datapath nl:K has a
440 corresponding virtual network device named ofK.
442 When in-band control is used, the location of the controller
443 may be configured manually or discovered automatically:
445 * Manual configuration: Start by bringing up of0 before
446 you start the secure channel:
450 Before the secure channel starts up, the of0 device
451 cannot send or receive any packets, so the next step
452 depends on whether connectivity is required to configure
453 the device's IP address:
455 . If the switch has a static IP address, you may
456 configure its IP address now, e.g.:
458 # ifconfig of0 192.168.1.1
460 . If the switch does not have a static IP address,
461 e.g. its IP address is obtained dynamically via
462 DHCP, then proceed to step 4. The DHCP client will
463 not be able to contact the DHCP server until the
464 secure channel has started up.
466 * Controller discovery: No special setup is required at
467 the switch, but you must specially configure a DHCP
468 server to give out the switch's IP address and to tell
469 it the location of the controller. See secchan(8) for
472 4. Run secchan on the datapath host to start the secure channel
473 connecting the datapath to a remote controller. (See secchan(8)
474 for usage details). The details depend on how you configured the
477 - If you are using in-band control and controller discovery,
478 invoke secchan something like this:
482 The secure channel should connect to the controller after it
483 obtains its own IP address and the controller's location via
484 DHCP. This can take a few seconds. Switch setup is now
487 - Otherwise, the secure channel should be configured to connect
488 to the controller's IP address on the port configured in step
489 2. If the controller is running on host 192.168.1.2 port 975
490 (the default port) and the datapath ID is 0, the secchan
491 invocation would look like:
493 # secchan -v nl:0 tcp:192.168.1.2
495 If you are using out-of-band control, or if you are using
496 in-band control and the switch has a static IP address, the
497 secure channel should quickly connect to the controller.
498 Setup is now complete. Otherwise, proceed to step 5.
500 5. If you are using the same network for control and data, and the
501 switch obtains its IP address dynamically, then you may now obtain
502 the switch's IP address, e.g. by invoking a DHCP client. The
503 secure channel will only be able to connect to the controller after
504 an IP address has been obtained.
509 Secure operation over SSL
510 -------------------------
512 The instructions above set up OpenFlow for operation over a plaintext
513 TCP connection. Production use of OpenFlow should use SSL[*] to
514 ensure confidentiality and authenticity of traffic among switches and
515 controllers. The source must be configured with --enable-ssl=yes to
516 build with SSL support.
518 To use SSL with OpenFlow, you must set up a public-key infrastructure
519 (PKI) including a pair of certificate authorities (CAs), one for
520 controllers and one for switches. If you have an established PKI,
521 OpenFlow can use it directly. Otherwise, refer to "Establishing a
522 Public Key Infrastructure" below.
524 To configure the controller to listen for SSL connections on port 976
525 (the default), invoke it as follows:
527 # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
530 where PRIVKEY is a file containing the controller's private key, CERT
531 is a file containing the controller CA's certificate for the
532 controller's public key, and CACERT is a file containing the root
533 certificate for the switch CA. If, for example, your PKI was created
534 with the instructions below, then the invocation would look like:
536 # controller -v pssl: --private-key=ctl-privkey.pem \
537 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
539 To configure a switch to connect to a controller running on port 976
540 (the default) on host 192.168.1.2 over SSL, invoke it as follows:
542 # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \
543 --certificate=CERT --ca-cert=CACERT
545 where INTERFACES is the command-separated list of network device
546 interfaces, PRIVKEY is a file containing the switch's private key,
547 CERT is a file containing the switch CA's certificate for the switch's
548 public key, and CACERT is a file containing the root certificate for
549 the controller CA. If, for example, your PKI was created with the
550 instructions below, then the invocation would look like:
552 # secchan -v -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \
553 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
555 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
556 specified by RFC 2246, which is very similar to SSL version 3.0.
557 TLSv1 was released in January 1999, so all current software and
558 hardware should implement it.
560 Establishing a Public Key Infrastructure
561 ----------------------------------------
563 If you do not have a PKI, the ofp-pki script included with OpenFlow
564 can help. To create an initial PKI structure, invoke it as:
566 which will create and populate a new directory named "pki" under the
569 The pki directory contains two important subdirectories. The
570 controllerca subdirectory contains controller certificate authority
571 related files, including the following:
573 - cacert.pem: Root certificate for the controller certificate
574 authority. This file must be provided to the switch or secchan
575 program with the --ca-cert option to enable it to authenticate
578 - private/cakey.pem: Private signing key for the controller
579 certificate authority. This file must be kept secret. There is
580 no need for switches or controllers to have a copy of it.
582 The switchca subdirectory contains switch certificate authority
583 related files, analogous to those in the controllerca subdirectory:
585 - cacert.pem: Root certificate for the switch certificate
586 authority. This file must be provided to the controller program
587 with the --ca-cert option to enable it to authenticate valid
590 - private/cakey.pem: Private signing key for the switch
591 certificate authority. This file must be kept secret. There is
592 no need for switches or controllers to have a copy of it.
594 After you create the initial structure, you can create keys and
595 certificates for switches and controllers with ofp-pki. To create a
596 controller private key and certificate in files named ctl-privkey.pem
597 and ctl-cert.pem, for example, you could run:
598 % ofp-pki req+sign ctl controller
599 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
600 controller for its use at runtime (they could then be deleted from
601 their original locations). The --private-key and --certificate
602 options of controller, respectively, would point to these files.
604 Analogously, to create a switch private key and certificate in files
605 named sc-privkey.pem and sc-cert.pem, for example, you could run:
606 % ofp-pki req+sign sc switch
607 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
608 for its use at runtime (they could then be deleted from their original
609 locations). The --private-key and --certificate options,
610 respectively, of switch and secchan would point to these files.
615 Please report problems to:
616 info@openflowswitch.org