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
25 To compile the datapath kernel module, you will additionally need:
27 - A supported Linux kernel version. Please refer to README for a
28 list of supported versions.
30 The OpenFlow datapath requires bridging support (CONFIG_BRIDGE)
31 to be built as a kernel module. (This is common in kernels
32 provided by Linux distributions.) The bridge module must not be
33 loaded or in use. If the bridge module is running (check with
34 "lsmod | grep bridge"), you must remove it ("rmmod bridge")
35 before starting the datapath.
37 - The correct version of GCC for the kernel that you are building
40 * To build a kernel module for a Linux 2.6 kernel, you need
41 the same version of GCC that was used to build that kernel
42 (usually version 4.0 or later).
44 * To build a kernel module for a Linux 2.4 kernel, you need an
45 earlier version of GCC, typically GCC 2.95, 3.3, or 3.4.
47 - A kernel build directory corresponding to the Linux kernel image
48 the module is to run on. Under Debian and Ubuntu, for example,
49 each linux-image package containing a kernel binary has a
50 corresponding linux-headers package with the required build
56 1. In the top source directory, configure the package by running the
57 configure script. To compile without building a kernel module, you
58 can usually invoke configure without any arguments:
61 To build a kernel module as well as the rest of the distribution,
62 pass the location of the kernel build directory as an argument.
63 Use --with-l26 for Linux 2.6, --with-l24 for Linux 2.4. For
64 example, to build for a running instance of Linux 2.6:
65 % ./configure --with-l26=/lib/modules/`uname -r`/build
67 To build for a running instance of Linux 2.4:
68 % ./configure --with-l24=/lib/modules/`uname -r`/build
70 To use a specific C compiler for compiling OpenFlow user programs,
71 also specify it on the configure command line, like so:
72 % ./configure CC=gcc-4.2
74 The configure script accepts a number of other options and honors a
75 additional environment variables. For a full list, invoke
76 configure with the --help option.
78 2. Run make in the top source directory:
81 The following binaries will be built:
83 Datapath kernel module:
84 datapath/linux-2.6/openflow_mod.ko (if --with-l26 was specified)
85 datapath/linux-2.4/openflow_mod.o (if --with-l24 was specified)
87 Secure channel executable:
90 Controller executable:
93 Datapath administration utility:
96 Runtime logging configuration utility:
99 3. (Optional) Run "make install" to install the executables and
100 manpages into the running system, by default under /usr/local.
102 Installing the datapath
103 -----------------------
105 To run the module, simply insmod it:
108 % insmod datapath/linux-2.6/openflow_mod.ko
111 % insmod datapath/linux-2.4/compat24_mod.o
112 % insmod datapath/linux-2.4/openflow_mod.o
118 Once the OpenFlow datapath has been installed (you can verify that it is
119 running if it appears in lsmod's listing), you can configure it using
120 the dpctl command line utility.
122 1. Create a datapath instance. The command below creates a datapath with
123 ID 0 (see dpctl(8) for more detailed usage information).
126 (note, while in principle openflow_mod supports multiple datapaths
127 within the same host, this is rarely useful in practice)
129 2. Use dpctl to attach the datapath to physical interfaces on the
130 machine. Say, for example, you want to create a trivial 2-port
131 switch using interfaces eth1 and eth2, you would issue the following
136 You can verify that the interfaces were successfully added by asking
137 dpctl to print the current status of datapath 0:
140 3. (Optional) You can manually add flows to the datapath to test using
141 dpctl add-flows and view them using dpctl dump-flows. See dpctl(8)
144 4. The simplest way to test the datapath is to run the provided sample
145 controller on the host machine to manage the datapath directly using
149 Once the controller is running, the datapath should operate like a
150 learning Ethernet switch. You may monitor the flows in the datapath
151 flow table using "dpctl dump-flows" command.
153 Running the datapath with a remote controller
154 ---------------------------------------------
156 1. Start the datapath and attach it to two or more physical ports as
157 described in the previous section.
159 Note: The current version of the secure channel and controller
160 require at least one interface not be connected to the datapath
161 to be functional. This interface will be used for communication
162 between the secure channel and the controller. Future releases will
163 support in-band control communication.
165 2. Run the controller in passive tcp mode on the host which will act as
166 the controller. In the example below, the controller will bind to
167 port 975 (the default) awaiting connections from secure channels.
168 % controller -v ptcp:
170 (See controller(8) for more details)
172 Make sure the machine hosting the controller is reachable by the switch.
174 3. Run secchan on the datapath host to start the secure channel
175 connecting the datapath to a remote controller. (See secchan(8)
176 for usage details). The channel should be configured to connect to
177 the controller's IP address on the port configured in step 2.
179 If the controller is running on host 192.168.1.2 port 975 (the
180 default port) and the datapath ID is 0, the secchan invocation
182 % secchan -v nl:0 tcp:192.168.1.2
184 Secure operation over SSL
185 -------------------------
187 The instructions above set up OpenFlow for operation over a plaintext
188 TCP connection. Production use of OpenFlow should use SSL[*] to
189 ensure confidentiality and authenticity of traffic among switches and
192 To use SSL with OpenFlow, you must set up a public-key infrastructure
193 (PKI) including a pair of certificate authorities (CAs), one for
194 controllers and one for switches. If you have an established PKI,
195 OpenFlow can use it directly. Otherwise, refer to "Establishing a
196 Public Key Infrastructure" below.
198 To configure the controller to listen for SSL connections on the
199 default port, invoke it as follows:
200 % controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
202 where PRIVKEY is a file containing the controller's private key, CERT
203 is a file containing the controller CA's certificate for the
204 controller's public key, and CACERT is a file containing the root
205 certificate for the switch CA. If, for example, your PKI was created
206 with the instructions below, then the invocation would look like:
207 % controller -v pssl: --private-key=ctl-privkey.pem \
208 --certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
210 To configure a switch to connect to a controller running on the
211 default port on host 192.168.1.2 over SSL, invoke it as follows:
212 % secchan -v nl:0 ssl:192.168.1.2 --private-key=PRIVKEY \
213 --certificate=CERT --ca-cert=CACERT
214 where PRIVKEY is a file containing the switch's private key, CERT is a
215 file containing the switch CA's certificate for the switch's public
216 key, and CACERT is a file containing the root certificate for the
217 controller CA. If, for example, your PKI was created with the
218 instructions below, then the invocation would look like:
219 % secchan -v nl:0 ssl:192.168.1.2 --private-key=sc-privkey.pem \
220 --certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
222 [*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
223 specified by RFC 2246, which is very similar to SSL version 3.0.
224 TLSv1 was released in January 1999, so all current software and
225 hardware should implement it.
227 Establishing a Public Key Infrastructure
228 ----------------------------------------
230 If you do not have a PKI, the ofp-pki script included with OpenFlow
231 can help. To create an initial PKI structure, invoke it as:
233 which will create and populate a new directory named "pki" under the
236 The pki directory contains two important subdirectories. The
237 controllerca subdirectory contains controller certificate authority
238 related files, including the following:
240 - cacert.pem: Root certificate for the controller certificate
241 authority. This file must be provided to the secchan
242 program with the --ca-cert option to enable it to
243 authenticate valid controllers.
245 - private/cakey.pem: Private signing key for the controller
246 certificate authority. This file must be kept secret. There is
247 no need for switches or controllers to have a copy of it.
249 The switchca subdirectory contains switch certificate authority
250 related files, analogous to those in the controllerca subdirectory:
252 - cacert.pem: Root certificate for the switch certificate
253 authority. This file must be provided to the controller program
254 with the --ca-cert option to enable it to authenticate valid
257 - private/cakey.pem: Private signing key for the switch
258 certificate authority. This file must be kept secret. There is
259 no need for switches or controllers to have a copy of it.
261 After you create the initial structure, you can create keys and
262 certificates for switches and controllers with ofp-pki. To create a
263 controller private key and certificate in files named ctl-privkey.pem
264 and ctl-cert.pem, for example, you could run:
265 % ofp-pki req+sign ctl controller
266 ctl-privkey.pem and ctl-cert.pem would need to be copied to the
267 controller for its use at runtime (they could then be deleted from
268 their original locations). The --private-key and --certificate
269 options of controller, respectively, would point to these files.
271 Analogously, to create a switch private key and certificate in files
272 named sc-privkey.pem and sc-cert.pem, for example, you could run:
273 % ofp-pki req+sign sc switch
274 sc-privkey.pem and sc-cert.pem would need to be copied to the switch
275 for its use at runtime (they could then be deleted from their original
276 locations). The --private-key and --certificate options of secchan,
277 respectively, would point to these files.
282 Please report problems to:
283 info@openflowswitch.org