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 The OpenFlow reference implementation includes two OpenFlow switch
14 - The "kernel-based switch": This divides the switch into a
15 "datapath" Linux kernel module (openflow_mod.o for Linux 2.4
16 or openflow_mod.ko for Linux 2.6) and a userspace program
17 (secchan). The kernel-based switch is faster than either of
18 the other two implementations but requires building and
19 installing a kernel module, which can sometimes be
22 - The "userspace datapath-based switch": This divides the
23 switch into a userspace "datapath" (built as
24 udatapath/udatapath) and the same userspace program used by
25 the kernel-based switch (secchan). The userspace
26 datapath-based switch does not require building a kernel
27 module, but it is not as fast as the kernel-based switch.
29 The reference implementation also contains a simple OpenFlow
30 controller (built as controller/controller) and a number of related
36 There are two principal ways to build and install this distribution:
38 - Using "configure" and "make" in the ordinary way. See
39 Building Conventionally below for detailed instructions.
41 - As a set of Debian packages. Refer to Building Debian
42 Packages, below, for instructions.
47 Regardless of how it is built, OpenFlow has a common set of
48 prerequisites. To compile the userspace programs in the OpenFlow
49 reference distribution, you will need the following software:
51 - A make program, e.g. GNU make
52 (http://www.gnu.org/software/make/). BSD make should also work.
54 - The GNU C compiler (http://gcc.gnu.org/). We generally test
55 with version 4.1 or 4.2.
57 - libssl, from OpenSSL (http://www.openssl.org/), is optional but
58 recommended. libssl is required to establish confidentiality
59 and authenticity in the connections among OpenFlow switches and
60 controllers. To enable, configure with --enable-ssl=yes.
62 If you are working from a Git tree or snapshot (instead of from a
63 distribution tarball), or if you modify the OpenFlow build system, you
64 will also need the following software:
66 - Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
68 - Automake version 1.10 or later (http://www.gnu.org/software/automake).
70 - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
76 To build Debian packages from the OpenFlow distribution, you will need
77 to install a number of Debian packages in addition to the base
78 prerequisites listed above. These additional prerequisites may be
79 found listed as "Build-Depends" in debian/control in the source tree.
80 To check that they are installed, first install the dpkg-dev package,
81 then run dpkg-checkbuilddeps from the top level of the OpenFlow source
84 To build Debian packages without being root, also install the
87 Kernel-Based Switch Prerequisites
88 ---------------------------------
90 The OpenFlow distribution also includes a Linux kernel module that can
91 be used to achieve higher switching performance. To compile the
92 kernel module, you must install the following in addition to the
93 software listed in the "Base Prerequisites" section above:
95 - A supported Linux kernel version. Please refer to README for a
96 list of supported versions.
98 The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
99 to be built as a kernel module. (This is common in kernels
100 provided by Linux distributions.) The bridge module must not be
101 loaded or in use. If the bridge module is running (check with
102 "lsmod | grep bridge"), you must remove it ("rmmod bridge")
103 before starting the datapath.
105 In kernels prior to 2.6.9, VLAN support (CONFIG_VLAN_8021Q) must
106 be compiled either directly or as a module. Failure to do this
107 will cause an error on module insertion due to the
108 "dev_change_flags" symbol being undefined.
110 - The correct version of GCC for the kernel that you are building
113 * To build a kernel module for a Linux 2.6 kernel, you need
114 the same version of GCC that was used to build that kernel
115 (usually version 4.0 or later).
117 * To build a kernel module for a Linux 2.4 kernel, you need an
118 earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
120 - A kernel build directory corresponding to the Linux kernel image
121 the module is to run on. Under Debian and Ubuntu, for example,
122 each linux-image package containing a kernel binary has a
123 corresponding linux-headers package with the required build
126 Building Conventionally
127 =======================
129 This section explains how to build and install the OpenFlow
130 distribution in the ordinary way using "configure" and "make".
132 0. Check that you have installed all the prerequisites listed above in
133 the Base Prerequisites section. If you want to compile the Linux
134 kernel module, also check that the prequisites listed under
135 Kernel-Based Switch Prequisites are installed.
137 1. In the top source directory, configure the package by running the
138 configure script. You can usually invoke configure without any
143 To use a specific C compiler for compiling OpenFlow user programs,
144 also specify it on the configure command line, like so:
146 % ./configure CC=gcc-4.2
148 To build the Linux kernel module, so that you can run the
149 kernel-based switch, add --with-l26 or --with-l24 option, or both,
150 to the configure script's command line. Refer to Building the
151 Linux Kernel-Based Switch, below, for more information.
153 The configure script accepts a number of other options and honors
154 additional environment variables. For a full list, invoke
155 configure with the --help option.
157 2. Run make in the top source directory:
161 The following binaries will be built:
163 - Userspace datapath: udatapath/udatapath.
165 - Secure channel executable: secchan/secchan.
167 - Controller executable: controller/controller.
169 - Datapath administration utility: utilities/dpctl.
171 - Runtime logging configuration utility: utilities/vlogconf.
173 - Miscellaneous utilities: utilities/ofp-discover,
176 - Tests: various binaries in tests/.
178 If your distribution includes the OpenFlow extensions, the
179 following additional binaries will be built:
181 - ANSI terminal support for EZIO 16x2 LCD panel:
184 - Switch monitoring UI for small text displays:
185 ext/ezio/ofp-switchui.
187 If you passed --with-l26 to configure, "make" will also build the
188 following kernel modules:
190 - datapath/linux-2.6/openflow_mod.ko
192 - datapath/linux-2.6/hwtable_<table>_mod.ko for each <table>
193 specified on --enable-hw-tables (if any).
195 If you passed --with-l24 to configure, "make" will also build the
196 following kernel modules:
198 - datapath/linux-2.4/openflow_mod.o
200 - datapath/linux-2.6/hwtable_<table>_mod.o for each <table>
201 specified on --enable-hw-tables (if any).
203 3. Run "make install" to install the executables and manpages into the
204 running system, by default under /usr/local.
206 4. If you built kernel modules, you may load them with "insmod", e.g.:
209 % insmod datapath/linux-2.6/openflow_mod.ko
212 % insmod datapath/linux-2.4/compat24_mod.o
213 % insmod datapath/linux-2.4/openflow_mod.o
215 After you load the openflow module, you may load one hardware switch
216 table module (if any were built) to enable support for that hardware
219 The insmod program must be run as root. You may need to specify a
220 full path to insmod, e.g. /sbin/insmod. To verify that the modules
221 have been loaded, run "/sbin/lsmod" and check that openflow_mod is
224 4. Test the userspace programs, as described under Testing Userspace
227 5. If you built the kernel module, test the kernel-based switch, as
228 described under Testing the Kernel-Based Implementation below.
230 Building the Linux Kernel-Based Switch
231 --------------------------------------
233 To build the kernel module, follow the build process described above,
234 but pass the location of the kernel build directory as an additional
235 argument to the configure script, as described under step 1 in that
236 section. Specify the location on --with-l26 for Linux 2.6, --with-l24
237 for Linux 2.4. For example, to build for a running instance of Linux
240 % ./configure --with-l26=/lib/modules/`uname -r`/build
242 To build for a running instance of Linux 2.4:
244 % ./configure --with-l24=/lib/modules/`uname -r`/build
246 If you wish to build OpenFlow for an architecture other than the
247 architecture used for compilation, you may specify the kernel
248 architecture string using the KARCH variable when invoking the
249 configure script. For example, to build OpenFlow for MIPS with Linux
252 % ./configure --with-l24=/path/to/linux-2.4 KARCH=mips
254 If you have hardware that supports accelerated OpenFlow switching, and
255 you have obtained a hardware table module for your hardware and
256 extracted it into the OpenFlow reference distribution source tree,
257 then you may also enable building support for the hardware switching
258 table with --enable-hw-tables. For example, if your hardware
259 switching table is in a directory named datapath/hwtable-foomatic, you
260 could compile support for it with the running Linux 2.6 kernel like
263 % ./configure --with-l26=/lib/modules/`uname -r`/build \
264 --enable-hw-tables=foomatic
266 For more information about hardware table modules, please read
267 README.hwtables at the root of the OpenFlow distribution tree.
269 Building Debian Packages
270 ========================
272 Follow these instructions to build Debian packages for OpenFlow.
274 0. Check that you have installed all the prerequisites listed above in
275 the Base Prerequisites and Debian Prerequisites sections above.
277 1. In the top source directory, run the following command, as root:
281 Alternatively, if you installed the "fakeroot" package, you may run
282 dpkg-buildpackage as an ordinary user with the following syntax:
284 % dpkg-buildpackage -rfakeroot
286 The following packages will be built in the directory above the
289 - openflow-controller: The OpenFlow controller. Depends on
290 openflow-pki (see below).
292 - openflow-switch: Install this package on a machine that acts
293 as an OpenFlow kernel switch.
295 - openflow-datapath-source: Source code for OpenFlow's Linux
298 - openflow-pki: Public-key infrastructure for OpenFlow. Install
299 this package on a machine that acts as an OpenFlow PKI server
300 (see "Establishing a Public Key Infrastructure" below).
302 - openflow-common: Files and utilities required by more than one
303 of the above packages.
305 2. To set up an OpenFlow controller, install the openflow-controller
306 package and its dependencies. You may configure it by editing
307 /etc/default/openflow-controller, e.g. to enable non-SSL
308 connections, which are disabled by default. If you change the
309 default settings, you will need to restart the controller by
312 % /etc/init.d/openflow-controller restart
314 3. To set up an OpenFlow switch, install the openflow-switch package
315 and its dependencies. If it is to be a kernel-based switch, also
316 install openflow-datapath-source, then follow the instructions in
317 /usr/share/doc/openflow-datapath-source/README.Debian to build and
318 install the kernel module.
320 You may configure the switch one of the following ways:
322 - Completely by hand, as described under the Testing section
325 For the userspace datapath-based switch, this is the only
326 supported form of configuration.
328 - By editing /etc/default/openflow-switch. You must at least
329 configure some network devices, by uncommenting NETDEVS and
330 adding the appropriate devices to the list, e.g. NETDEVS="eth0
333 After you edit this file, you will need to start the switch by
336 % /etc/init.d/openflow-switch restart
338 This form of configuration is not supported for the userspace
339 datapath-based switch.
341 - By running the ofp-switch-setup program. This interactive
342 program will walk you through all the steps of configuring an
343 OpenFlow switch, including configuration of SSL certificates.
344 Run it without arguments, as root:
348 This form of configuration is not supported for the userspace
349 datapath-based switch.
354 The following sets of instructions show how to use the OpenFlow
355 reference implementation as a switch on a single machine. This can be
356 used to verify that the distribution built properly. For full
357 installation instructions, refer to the Installation section below.
362 These instructions use the OpenFlow userspace datapath ("udatapath").
364 1. Start the OpenFlow controller running in the background, by running
365 the "controller" program with a command like the following:
367 # controller punix:/var/run/controller.sock &
369 This command causes the controller to bind to the specified Unix
370 domain socket, awaiting connections from OpenFlow switches. See
371 controller(8) for details.
373 The "controller" program does not require any special privilege, so
374 you do not need to run it as root.
376 2. The commands below must run as root, so log in as root, or use a
377 program such as "su" to become root temporarily.
379 3. Create a datapath instance running in the background. The command
380 below creates a datapath that listens for connections from secchan
381 on a Unix domain socket located in /var/run and services physical
384 # udatapath punix:/var/run/dp0.sock -i eth1,eth2 &
386 4. Run secchan to start the secure channel connecting the datapath and
389 # secchan unix:/var/run/controller.sock unix:/var/run/dp0.sock &
391 5. Devices plugged into the network ports specified in step 2 should
392 now be able to send packets to each other, as if they were plugged
393 into ports on a conventional Ethernet switch.
398 This section explains how to install OpenFlow in a network with one
399 controller and one or more switches, each of which runs on a separate
400 machine. Before you begin, you must decide on one of two ways for
401 each switch to reach the controller over the network:
403 - Use a "control network" that is completely separate from the
404 "data network" to be controlled ("out-of-band control"). The
405 location of the controller must be configured manually in this
408 - Use the same network for control and for data ("in-band
409 control"). When in-band control is used, the location of the
410 controller may be configured manually or discovered
411 automatically. We will assume manual configuration here;
412 please refer to secchan(8) for instructions on setting up
413 controller discovery.
418 On the machine that is to be the OpenFlow controller, start the
419 "controller" program listening for connections from switches on TCP
420 port 6633 (the default), as shown below.
422 # controller -v ptcp:
424 (See controller(8) for more details)
426 Make sure the machine hosting the controller is reachable by the
429 Userspace Datapath-Based Setup
430 ------------------------------
432 On a machine that is to host an OpenFlow userspace datapath-based
433 switch, follow the procedure below.
435 0. The commands below must run as root, so log in as root, or use a
436 program such as "su" to become root temporarily.
438 1. Create a datapath instance running in the background. The command
439 below creates a datapath that listens for connections from secchan
440 on a Unix domain socket located in /var/run, services physical
441 ports eth1 and eth2, and creates a TAP network device named "tap0"
442 for use in in-band control:
444 # udatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 &
446 (See udatapath(8) for details.)
448 If the switch will connect to the controller out-of-band, then the
449 --local-port option may be omitted, or --no-local-port may be
452 3. Arrange so that the switch can reach the controller over the
455 - If you are using out-of-band control, at this point make sure
456 that the switch machine can reach the controller over the
459 - If you are using in-band control with manual configuration, at
460 this point the TAP network device created in step 1 is not
461 bridged to any physical network, so the next step depends on
462 whether connectivity is required to configure the device's IP
465 * If the switch has a static IP address, you may configure
466 its IP address now, e.g.:
468 # ifconfig tap0 192.168.1.1
470 * If the switch does not have a static IP address, e.g. its
471 IP address is obtained dynamically via DHCP, then proceed
472 to step 4. The DHCP client will not be able to contact
473 the DHCP server until the secure channel has started up.
475 - If you are using in-band control with controller discovery, no
476 configuration is required at this point. You may proceed to
479 4. Run secchan to start the secure channel connecting the datapath to
480 a remote controller. If the controller is running on host
481 192.168.1.2 port 6633 (the default port), the secchan invocation
482 would look like this:
484 # secchan unix:/var/run/dp0.sock tcp:192.168.1.2
486 - If you are using in-band control with controller discovery, omit
487 the second argument to the secchan command.
489 - If you are using out-of-band control, add --out-of-band to the
492 5. If you are using in-band control with manual configuration, and the
493 switch obtains its IP address dynamically, then you may now obtain
494 the switch's IP address, e.g. by invoking a DHCP client. The
495 secure channel will only be able to connect to the controller after
496 an IP address has been obtained.
498 6. The secure channel should connect to the controller within a few
499 seconds. It may take a little longer if controller discovery is in
500 use, because the switch must then also obtain its own IP address
501 and the controller's location via DHCP.
503 Testing the Kernel-Based Implementation
504 ---------------------------------------
506 The OpenFlow kernel module must be loaded, as described under
507 "Building Conventionally", before it may be used.
509 0. The commands below must run as root, so log in as root, or use a
510 program such as "su" to become root temporarily.
512 1. Create a datapath instance. The command below creates a datapath
513 identified as nl:0 (see dpctl(8) for more detailed usage
518 (nl:0 is the first datapath within a host. openflow_mod supports
519 multiple datapaths within the same host, which would be identified
522 Creating datapath nl:0 also creates a new network device named of0.
523 This network device, called the datapath's "local port", will be
524 bridged to the physical switch ports by the secchan, for use in
527 If you built a support module for hardware accelerated OpenFlow
528 switching and you want to use it, you must load it before creating
529 the datapath with "dpctl adddp".
531 2. Use dpctl to attach the datapath to physical interfaces on the
532 machine. Say, for example, you want to create a trivial 2-port
533 switch using interfaces eth1 and eth2, you would issue the following
536 # dpctl addif nl:0 eth1
537 # dpctl addif nl:0 eth2
539 You can verify that the interfaces were successfully added by asking
540 dpctl to print the current status of datapath nl:0:
544 3. Arrange so that the switch can reach the controller over the
547 - If you are using out-of-band control, at this point make sure
548 that the switch machine can reach the controller over the
551 - If you are using in-band control, then at this point you must
552 configure the of0 network device created in step 1. This
553 device is not yet bridged to any physical network (because
554 secchan does that, and it is not yet running), so the next
555 step depends on whether connectivity is required to configure
556 the device's IP address:
558 * If the switch has a static IP address, you may configure
559 its IP address now, e.g.:
561 # ifconfig of0 192.168.1.1
563 * If the switch does not have a static IP address, e.g. its
564 IP address is obtained dynamically via DHCP, then proceed
565 to step 4. The DHCP client will not be able to contact
566 the DHCP server until the secure channel has started up.
568 - If you are using in-band control with controller discovery, no
569 configuration is required at this point. You may proceed to
572 4. Run secchan to start the secure channel connecting the datapath to
573 a remote controller. If the controller is running on host
574 192.168.1.2 port 6633 (the default port), the secchan invocation
575 would look like this:
577 # secchan nl:0 tcp:192.168.1.2
579 - If you are using in-band control with controller discovery, omit
580 the second argument to the secchan command.
582 - If you are using out-of-band control, add --out-of-band to the
585 5. If you are using in-band control with manual configuration, and the
586 switch obtains its IP address dynamically, then you may now obtain
587 the switch's IP address, e.g. by invoking a DHCP client. The
588 secure channel will only be able to connect to the controller after
589 an IP address has been obtained.
591 6. The secure channel should connect to the controller within a few
592 seconds. It may take a little longer if controller discovery is in
593 use, because the switch must then also obtain its own IP address
594 and the controller's location via DHCP.
599 Secure operation over SSL
600 -------------------------
602 The instructions above set up OpenFlow for operation over a plaintext
603 TCP connection. Production use of OpenFlow should use SSL[*] to
604 ensure confidentiality and authenticity of traffic among switches and
605 controllers. The source must be configured with --enable-ssl=yes to
606 build with SSL support.
608 To use SSL with OpenFlow, you must set up a public-key infrastructure
609 (PKI) including a pair of certificate authorities (CAs), one for
610 controllers and one for switches. If you have an established PKI,
611 OpenFlow can use it directly. Otherwise, refer to "Establishing a
612 Public Key Infrastructure" below.
614 To configure the controller to listen for SSL connections on port 6633
615 (the default), invoke it as follows:
617 # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
620 where PRIVKEY is a file containing the controller's private key, CERT
621 is a file containing the controller CA's certificate for the
622 controller's public key, and CACERT is a file containing the root
623 certificate for the switch CA. If, for example, your PKI was created
624 with the instructions below, then the invocation would look like:
626 # controller -v pssl: --private-key=ctl-privkey.pem \
627 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
629 To configure a switch to connect to a controller running on port 6633
630 (the default) on host 192.168.1.2 over SSL, invoke secchan as follows:
632 # secchan -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
633 --certificate=CERT --ca-cert=CACERT
635 where DATAPATH is the datapath to connect to (e.g. nl:0 or
636 unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
637 private key, CERT is a file containing the switch CA's certificate for
638 the switch's public key, and CACERT is a file containing the root
639 certificate for the controller CA. If, for example, your PKI was
640 created with the instructions below, then the invocation would look
643 # secchan -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
644 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
646 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
647 specified by RFC 2246, which is very similar to SSL version 3.0.
648 TLSv1 was released in January 1999, so all current software and
649 hardware should implement it.
651 Establishing a Public Key Infrastructure
652 ----------------------------------------
654 If you do not have a PKI, the ofp-pki script included with OpenFlow
655 can help. To create an initial PKI structure, invoke it as:
657 which will create and populate a new PKI directory. The default
658 location for the PKI directory depends on how the OpenFlow tree was
659 configured (to see the configured default, look for the --dir option
660 description in the output of "ofp-pki --help").
662 The pki directory contains two important subdirectories. The
663 controllerca subdirectory contains controller certificate authority
664 related files, including the following:
666 - cacert.pem: Root certificate for the controller certificate
667 authority. This file must be provided to secchan with the
668 --ca-cert option to enable it to authenticate valid controllers.
670 - private/cakey.pem: Private signing key for the controller
671 certificate authority. This file must be kept secret. There is
672 no need for switches or controllers to have a copy of it.
674 The switchca subdirectory contains switch certificate authority
675 related files, analogous to those in the controllerca subdirectory:
677 - cacert.pem: Root certificate for the switch certificate
678 authority. This file must be provided to the controller program
679 with the --ca-cert option to enable it to authenticate valid
682 - private/cakey.pem: Private signing key for the switch
683 certificate authority. This file must be kept secret. There is
684 no need for switches or controllers to have a copy of it.
686 After you create the initial structure, you can create keys and
687 certificates for switches and controllers with ofp-pki. To create a
688 controller private key and certificate in files named ctl-privkey.pem
689 and ctl-cert.pem, for example, you could run:
690 % ofp-pki req+sign ctl controller
691 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
692 controller for its use at runtime (they could then be deleted from
693 their original locations). The --private-key and --certificate
694 options of controller, respectively, would point to these files.
696 Analogously, to create a switch private key and certificate in files
697 named sc-privkey.pem and sc-cert.pem, for example, you could run:
698 % ofp-pki req+sign sc switch
699 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
700 for its use at runtime (they could then be deleted from their original
701 locations). The --private-key and --certificate options,
702 respectively, of secchan would point to these files.
707 Please report problems to:
708 info@openflowswitch.org