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 To compile the userspace programs in the OpenFlow reference
12 distribution, you will need the following software:
14 - A make program, e.g. GNU make
15 (http://www.gnu.org/software/make/). BSD make should also work.
17 - The GNU C compiler (http://gcc.gnu.org/). We generally test
18 with version 4.1 or 4.2.
20 - libssl, from OpenSSL (http://www.openssl.org/), is optional but
21 recommended. libssl is required to establish confidentiality
22 and authenticity in the connections among OpenFlow switches and
23 controllers. To enable, compile with --enable-ssl=yes
25 If you are working from a Git tree or snapshot (instead of from a
26 distribution tarball), or if you modify the OpenFlow build system, you
27 will also need the following software:
29 - Autoconf version 2.59 or later (http://www.gnu.org/software/autoconf).
31 - Automake version 1.10 or later (http://www.gnu.org/software/automake).
33 - pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
36 The optional Linux module has additional prerequisites, described
37 later in the section "Building and Testing the Linux Kernel-Based
40 Building Userspace Programs
41 ---------------------------
43 The OpenFlow distribution includes two implementations of the switch:
44 one entirely in userspace, for portability and ease of installation,
45 and another with a Linux kernel module component that is more
46 difficult to install but should also yield better performance. These
47 instructions describe how to build the userspace components of the
48 OpenFlow distribution. Refer to "Building and Testing the Linux
49 Kernel-Based Switch", below, for additional instructions on how to
50 build the optional Linux kernel module.
52 1. In the top source directory, configure the package by running the
53 configure script. You can usually invoke configure without any
58 To use a specific C compiler for compiling OpenFlow user programs,
59 also specify it on the configure command line, like so:
61 % ./configure CC=gcc-4.2
63 The configure script accepts a number of other options and honors
64 additional environment variables. For a full list, invoke
65 configure with the --help option.
67 2. Run make in the top source directory:
71 The following binaries will be built:
73 - Switch executable: switch/switch. This executable is built
74 only if the configure script detects a supported interface to
75 network devices. Refer to README for a list of OSes whose
76 network device interfaces are supported.
78 - Secure channel executable: secchan/secchan.
80 - Controller executable: controller/controller.
82 - Datapath administration utility: utilities/dpctl.
84 - Runtime logging configuration utility: utilities/vlogconf.
86 3. (Optional) Run "make install" to install the executables and
87 manpages into the running system, by default under /usr/local.
89 Testing Userspace Programs
90 --------------------------
92 0. The commands below must run as root, so log in as root, or use a
93 program such as "su" to become root temporarily.
95 1. Start the OpenFlow controller running in the background, by running
96 the "controller" program with a command like the following:
100 This command causes the controller to bind to port 975 (the
101 default) awaiting connections from OpenFlow switches. See
102 controller(8) for details.
104 2. On the same machine, use the "switch" program to start an OpenFlow
105 switch, specifying network devices to use as switch ports on the -i
106 option as a comma-separated list, like so:
108 # switch tcp:127.0.0.1 -i eth1,eth2
110 The network devices that you specify should not have configured IP
113 3. The controller causes each switch that connects to it to act like a
114 learning Ethernet switch. Thus, devices plugged into the specified
115 network ports should now be able to send packets to each other, as
116 if they were plugged into ports on a conventional Ethernet switch.
118 Troubleshooting: if the commands above do not work, try using the -v
119 or --verbose option on the controller or switch commands, which will
120 cause a large amount of debug output from each program.
122 Remote switches: These instructions assume that the controller and the
123 switch are running on the same machine. This is an easy configuration
124 for testing, but a more conventional setup would run a controller on
125 one machine and one or more switches on different machines. To do so,
126 simply specify the IP address of the controller as the first argument
127 to the switch program (in place of 127.0.0.1). (Note: The userspace
128 switch must be connected to the controller over a "control network"
129 that is physically separate from the one that the switch and
130 controller are controlling. The kernel-based switch does not have
133 Secure operation over SSL
134 -------------------------
136 The instructions above set up OpenFlow for operation over a plaintext
137 TCP connection. Production use of OpenFlow should use SSL[*] to
138 ensure confidentiality and authenticity of traffic among switches and
139 controllers. The source must be configured with --enable-ssl=yes to
140 build with ssl support.
142 To use SSL with OpenFlow, you must set up a public-key infrastructure
143 (PKI) including a pair of certificate authorities (CAs), one for
144 controllers and one for switches. If you have an established PKI,
145 OpenFlow can use it directly. Otherwise, refer to "Establishing a
146 Public Key Infrastructure" below.
148 To configure the controller to listen for SSL connections on port 976
149 (the default), invoke it as follows:
151 # controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
154 where PRIVKEY is a file containing the controller's private key, CERT
155 is a file containing the controller CA's certificate for the
156 controller's public key, and CACERT is a file containing the root
157 certificate for the switch CA. If, for example, your PKI was created
158 with the instructions below, then the invocation would look like:
160 # controller -v pssl: --private-key=ctl-privkey.pem \
161 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
163 To configure a switch to connect to a controller running on port 976
164 (the default) on host 192.168.1.2 over SSL, invoke it as follows:
166 # switch -v ssl:192.168.1.2 -i INTERFACES --private-key=PRIVKEY \
167 --certificate=CERT --ca-cert=CACERT
169 where INTERFACES is the command-separated list of network device
170 interfaces, PRIVKEY is a file containing the switch's private key,
171 CERT is a file containing the switch CA's certificate for the switch's
172 public key, and CACERT is a file containing the root certificate for
173 the controller CA. If, for example, your PKI was created with the
174 instructions below, then the invocation would look like:
176 # secchan -v -i INTERFACES ssl:192.168.1.2 --private-key=sc-privkey.pem \
177 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
179 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
180 specified by RFC 2246, which is very similar to SSL version 3.0.
181 TLSv1 was released in January 1999, so all current software and
182 hardware should implement it.
184 Establishing a Public Key Infrastructure
185 ----------------------------------------
187 If you do not have a PKI, the ofp-pki script included with OpenFlow
188 can help. To create an initial PKI structure, invoke it as:
190 which will create and populate a new directory named "pki" under the
193 The pki directory contains two important subdirectories. The
194 controllerca subdirectory contains controller certificate authority
195 related files, including the following:
197 - cacert.pem: Root certificate for the controller certificate
198 authority. This file must be provided to the switch or secchan
199 program with the --ca-cert option to enable it to authenticate
202 - private/cakey.pem: Private signing key for the controller
203 certificate authority. This file must be kept secret. There is
204 no need for switches or controllers to have a copy of it.
206 The switchca subdirectory contains switch certificate authority
207 related files, analogous to those in the controllerca subdirectory:
209 - cacert.pem: Root certificate for the switch certificate
210 authority. This file must be provided to the controller program
211 with the --ca-cert option to enable it to authenticate valid
214 - private/cakey.pem: Private signing key for the switch
215 certificate authority. This file must be kept secret. There is
216 no need for switches or controllers to have a copy of it.
218 After you create the initial structure, you can create keys and
219 certificates for switches and controllers with ofp-pki. To create a
220 controller private key and certificate in files named ctl-privkey.pem
221 and ctl-cert.pem, for example, you could run:
222 % ofp-pki req+sign ctl controller
223 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
224 controller for its use at runtime (they could then be deleted from
225 their original locations). The --private-key and --certificate
226 options of controller, respectively, would point to these files.
228 Analogously, to create a switch private key and certificate in files
229 named sc-privkey.pem and sc-cert.pem, for example, you could run:
230 % ofp-pki req+sign sc switch
231 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
232 for its use at runtime (they could then be deleted from their original
233 locations). The --private-key and --certificate options,
234 respectively, of switch and secchan would point to these files.
236 Building and Testing the Linux Kernel-Based Switch
237 --------------------------------------------------
239 The OpenFlow distribution also includes a Linux kernel module that can
240 be used to achieve higher switching performance at a cost in
241 portability and ease of installation. Compiling the kernel module has
242 the following prerequisites in addition to those listed in the
243 "Prerequisites" section above:
245 - A supported Linux kernel version. Please refer to README for a
246 list of supported versions.
248 The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
249 to be built as a kernel module. (This is common in kernels
250 provided by Linux distributions.) The bridge module must not be
251 loaded or in use. If the bridge module is running (check with
252 "lsmod | grep bridge"), you must remove it ("rmmod bridge")
253 before starting the datapath.
255 - The correct version of GCC for the kernel that you are building
258 * To build a kernel module for a Linux 2.6 kernel, you need
259 the same version of GCC that was used to build that kernel
260 (usually version 4.0 or later).
262 * To build a kernel module for a Linux 2.4 kernel, you need an
263 earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
265 - A kernel build directory corresponding to the Linux kernel image
266 the module is to run on. Under Debian and Ubuntu, for example,
267 each linux-image package containing a kernel binary has a
268 corresponding linux-headers package with the required build
271 To build the kernel module, follow the build process described under
272 "Building Userspace Programs" above, but pass the location of the
273 kernel build directory as an additional argument to the configure
274 script, as described under step 1 in that section. Specify the
275 location on --with-l26 for Linux 2.6, --with-l24 for Linux 2.4. For
276 example, to build for a running instance of Linux 2.6:
278 % ./configure --with-l26=/lib/modules/`uname -r`/build
280 To build for a running instance of Linux 2.4:
282 % ./configure --with-l24=/lib/modules/`uname -r`/build
284 If you have hardware that supports accelerated OpenFlow switching, and
285 you have obtained a hardware table module for your hardware and
286 extracted it into the OpenFlow reference distribution source tree,
287 then you may also enable building support for the hardware switching
288 table with --enable-hw-tables. For example, if your hardware
289 switching table is in a directory named datapath/hwtable-foomatic, you
290 could compile support for it with the running Linux 2.6 kernel like
293 % ./configure --with-l26=/lib/modules/`uname -r`/build \
294 --enable-hw-tables=foomatic
296 For more information about hardware table modules, please read
297 README.hwtables at the root of the OpenFlow distribution tree.
299 In addition to the binaries listed under step 2 in "Building Userspace
300 Programs" above, "make" will build the following kernel modules:
302 datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
303 datapath/linux-2.4/openflow_mod.o (if --with-l24 was specified)
305 "make" will also build a kernel module for each hardware switch table
306 enabled with --enable-hw-tables.
308 Once you have built the kernel modules, activating them requires only
309 running "insmod", e.g.:
312 % insmod datapath/linux-2.6/openflow_mod.ko
315 % insmod datapath/linux-2.4/compat24_mod.o
316 % insmod datapath/linux-2.4/openflow_mod.o
318 After you load the openflow module, you may load one hardware switch
319 table module (if any were built) to enable support for that hardware
322 The insmod program must be run as root. You may need to specify a
323 full path to insmod, which is usually in the /sbin directory. To
324 verify that the modules have been loaded, run "lsmod" (also in /sbin)
325 and check that openflow_mod appears in the result.
327 Testing the Kernel-Based Implementation
328 ---------------------------------------
330 The OpenFlow kernel module must be loaded, as described in the
331 previous section, before it may be tested.
333 0. The commands below must run as root, so log in as root, or use a
334 program such as "su" to become root temporarily.
336 1. Create a datapath instance. The command below creates a datapath with
337 ID 0 (see dpctl(8) for more detailed usage information).
341 In principle, openflow_mod supports multiple datapaths within the
342 same host, but this is rarely useful in practice.
344 If you built a support module for hardware accelerated OpenFlow
345 switching and you want to use it, you must load it before creating
346 the datapath with "dpctl adddp".
348 2. Use dpctl to attach the datapath to physical interfaces on the
349 machine. Say, for example, you want to create a trivial 2-port
350 switch using interfaces eth1 and eth2, you would issue the following
356 You can verify that the interfaces were successfully added by asking
357 dpctl to print the current status of datapath 0:
361 3. (Optional) You can manually add flows to the datapath to test using
362 dpctl add-flows and view them using dpctl dump-flows. See dpctl(8)
365 4. The simplest way to test the datapath is to run the provided sample
366 controller on the host machine to manage the datapath directly using
371 Once the controller is running, the datapath should operate like a
372 learning Ethernet switch. You may monitor the flows in the datapath
373 flow table using "dpctl dump-flows" command.
375 The preceding instructions assume that the controller and the switch
376 are running on the same machine. This is an easy configuration for
377 testing, but a more conventional setup would run a controller on one
378 machine and one or more switches on different machines. Use the
379 following instructions to set up remote switches:
381 1. Start the datapath and attach it to two or more physical ports as
382 described in the previous section.
384 2. Run the controller in passive tcp mode on the host which will act as
385 the controller. In the example below, the controller will bind to
386 port 975 (the default) awaiting connections from secure channels.
388 # controller -v ptcp:
390 (See controller(8) for more details)
392 Make sure the machine hosting the controller is reachable by the switch.
394 3. Arrange so that the switch can reach the controller over the
395 network. There are two ways to do this:
397 - Use a "control network" that is completely separate from the
398 "data network" to be controlled. To do so, configure a
399 network device (one that has not been added to the datapath
400 with "dpctl addif") to access the control network in the usual
403 - Use the same network for control and for data. For this
404 purpose, each datapath nl:K has a corresponding virtual
405 network device named ofK. Start by bringing up of0 before you
406 start the secure channel:
410 Before the secure channel starts up, the of0 device cannot
411 send or receive any packets, so the next step depends on
412 whether connectivity is required to configure the device's IP
415 . If the switch has a static IP address, you may configure
416 its IP address now, e.g.:
418 # ifconfig of0 192.168.1.1
420 . If the switch does not have a static IP address, e.g. its
421 IP address is obtained dynamically via DHCP, then proceed
422 to step 4. The DHCP client will not be able to contact
423 the DHCP server until the secure channel has started up.
425 4. Run secchan on the datapath host to start the secure channel
426 connecting the datapath to a remote controller. (See secchan(8)
427 for usage details). The channel should be configured to connect to
428 the controller's IP address on the port configured in step 2.
430 If the controller is running on host 192.168.1.2 port 975 (the
431 default port) and the datapath ID is 0, the secchan invocation
434 # secchan -v nl:0 tcp:192.168.1.2
436 If you are using separate control and data networks, or if the
437 networks are combined and the switch has a static IP address, the
438 secure channel should quickly connect to the controller. Setup is
439 now complete. Otherwise, proceed to step 5.
441 5. If you are using the same network for control and data, and the
442 switch obtains its IP address dynamically, then you may now obtain
443 the switch's IP address, e.g. by invoking a DHCP client. The
444 secure channel will only be able to connect to the controller after
445 an IP address has been obtained.
450 Please report problems to:
451 info@openflowswitch.org