-
Notifications
You must be signed in to change notification settings - Fork 22
/
INSTALL
406 lines (292 loc) · 15.6 KB
/
INSTALL
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
Installation Instructions for OpenFlow Reference Release
This document describes how to build, install, and execute the
reference implementation of OpenFlow. Please send any comments to:
Contents
========
The OpenFlow reference implementation includes one OpenFlow switch
implementations:
- The "userspace datapath-based switch": This divides the switch
into a userspace "datapath" (built as udatapath/ofdatapath)
and a userspace program that implements the secure channel
component (ofprotocol). The userspace datapath-based switch
does not require building a kernel module, but it is not as
fast as a kernel-based switch.
The reference implementation also contains a simple OpenFlow
controller (built as controller/controller) and a number of related
utilities.
Build Methods
=============
There are two principal ways to build and install this distribution:
- Using "configure" and "make" in the ordinary way. See
Building Conventionally below for detailed instructions.
- As a set of Debian packages. Refer to Building Debian
Packages, below, for instructions.
Base Prerequisites
------------------
Regardless of how it is built, OpenFlow has a common set of
prerequisites. To compile the userspace programs in the OpenFlow
reference distribution, you will need the following software:
- A make program, e.g. GNU make
(http://www.gnu.org/software/make/). BSD make should also work.
- The GNU C compiler (http://gcc.gnu.org/). We generally test
with version 4.1 or 4.2.
- libssl, from OpenSSL (http://www.openssl.org/), is optional but
recommended. libssl is required to establish confidentiality
and authenticity in the connections among OpenFlow switches and
controllers. To enable, configure with --enable-ssl=yes.
If you are working from a Git tree or snapshot (instead of from a
distribution tarball), or if you modify the OpenFlow build system, you
will also need the following software:
- Autoconf version 2.60 or later (http://www.gnu.org/software/autoconf).
- Automake version 1.10 or later (http://www.gnu.org/software/automake).
- pkg-config (http://pkg-config.freedesktop.org/wiki/). We test
with version 0.22.
Debian Prerequisites
--------------------
To build Debian packages from the OpenFlow distribution, you will need
to install a number of Debian packages in addition to the base
prerequisites listed above. These additional prerequisites may be
found listed as "Build-Depends" in debian/control in the source tree.
To check that they are installed, first install the dpkg-dev package,
then run dpkg-checkbuilddeps from the top level of the OpenFlow source
tree.
To build Debian packages without being root, also install the
"fakeroot" package.
Userspace Switch Prerequisites
---------------------------------
- To enable slicing support, "tc" frontend should be installed
(from iproute2, part of all major distributions,
http://www.linux-foundation.org/en/Net:Iproute2).
You also need to enable the following kernel configuration
options under the QoS and/or Fair queueing section :
CONFIG_NET_SCHED,CONFIG_NET_SCH_HTB (already configured that
way in most distributions).
(NOTE: You can disable slicing (and these dependencies) at runtime
using the --no-slicing option)
Building Conventionally
=======================
This section explains how to build and install the OpenFlow
distribution in the ordinary way using "configure" and "make".
0. Check that you have installed all the prerequisites listed above in
the Base Prerequisites section.
1. In the top source directory, configure the package by running the
configure script. You can usually invoke configure without any
arguments:
% ./configure
To use a specific C compiler for compiling OpenFlow user programs,
also specify it on the configure command line, like so:
% ./configure CC=gcc-4.2
The configure script accepts a number of other options and honors
additional environment variables. For a full list, invoke
configure with the --help option.
2. Run make in the top source directory:
% make
The following binaries will be built:
- Userspace datapath: udatapath/ofdatapath.
- Secure channel executable: secchan/ofprotocol.
- Datapath administration utility: utilities/dpctl.
- Runtime logging configuration utility: utilities/vlogconf.
- Miscellaneous utilities: utilities/ofp-discover,
utilities/ofp-kill.
3. Run "make install" to install the executables and manpages into the
running system, by default under /usr/local.
4. Test the userspace programs, as described under Testing Userspace
Programs below.
Building Debian Packages
========================
Follow these instructions to build Debian packages for OpenFlow.
0. Check that you have installed all the prerequisites listed above in
the Base Prerequisites and Debian Prerequisites sections above.
1. In the top source directory, run the following command, as root:
% dpkg-buildpackage
Alternatively, if you installed the "fakeroot" package, you may run
dpkg-buildpackage as an ordinary user with the following syntax:
% dpkg-buildpackage -rfakeroot
The following packages will be built in the directory above the
source tree:
- openflow-pki: Public-key infrastructure for OpenFlow. Install
this package on a machine that acts as an OpenFlow PKI server
(see "Establishing a Public Key Infrastructure" below).
- openflow-common: Files and utilities required by more than one
of the above packages.
2. To set up an OpenFlow switch, install the openflow-switch package
and its dependencies.
You may configure the switch one of the following ways:
- By editing /etc/default/openflow-switch. You must at least
configure some network devices, by uncommenting NETDEVS and
adding the appropriate devices to the list, e.g. NETDEVS="eth0
eth1".
After you edit this file, you will need to start the switch by
running:
% /etc/init.d/openflow-switch restart
This form of configuration is not supported for the userspace
datapath-based switch.
- By running the ofp-switch-setup program. This interactive
program will walk you through all the steps of configuring an
OpenFlow switch, including configuration of SSL certificates.
Run it without arguments, as root:
% ofp-switch-setup
This form of configuration is not supported for the userspace
datapath-based switch.
Installation
============
This section explains how to install OpenFlow in a network with one
controller and one or more switches, each of which runs on a separate
machine. Before you begin, you must decide on one of two ways for
each switch to reach the controller over the network:
- Use a "control network" that is completely separate from the
"data network" to be controlled ("out-of-band control"). The
location of the controller must be configured manually in this
case.
- Use the same network for control and for data ("in-band
control"). When in-band control is used, the location of the
controller may be configured manually or discovered
automatically. We will assume manual configuration here;
please refer to ofprotocol(8) for instructions on setting up
controller discovery.
Userspace Datapath-Based Setup
------------------------------
On a machine that is to host an OpenFlow userspace datapath-based
switch, follow the procedure below.
0. The commands below must run as root, so log in as root, or use a
program such as "su" to become root temporarily.
1. Create a datapath instance running in the background. The command
below creates a datapath that listens for connections from ofprotocol
on a Unix domain socket located in /var/run, services physical
ports eth1 and eth2, and creates a TAP network device named "tap0"
for use in in-band control:
# ofdatapath punix:/var/run/dp0.sock -i eth1,eth2 --local-port=tap:tap0 &
(See ofdatapath(8) for details.)
If the switch will connect to the controller out-of-band, then the
--local-port option may be omitted, or --no-local-port may be
substituted.
3. Arrange so that the switch can reach the controller over the
network.
- If you are using out-of-band control, at this point make sure
that the switch machine can reach the controller over the
network.
- If you are using in-band control with manual configuration, at
this point the TAP network device created in step 1 is not
bridged to any physical network, so the next step depends on
whether connectivity is required to configure the device's IP
address:
* If the switch has a static IP address, you may configure
its IP address now, e.g.:
# ifconfig tap0 192.168.1.1
* If the switch does not have a static IP address, e.g. its
IP address is obtained dynamically via DHCP, then proceed
to step 4. The DHCP client will not be able to contact
the DHCP server until the secure channel has started up.
- If you are using in-band control with controller discovery, no
configuration is required at this point. You may proceed to
step 4.
4. Run ofprotocol to start the secure channel connecting the datapath to
a remote controller. If the controller is running on host
192.168.1.2 port 6633 (the default port), the ofprotocol invocation
would look like this:
# ofprotocol unix:/var/run/dp0.sock tcp:192.168.1.2
- If you are using in-band control with controller discovery, omit
the second argument to the ofprotocol command.
- If you are using out-of-band control, add --out-of-band to the
command line.
5. If you are using in-band control with manual configuration, and the
switch obtains its IP address dynamically, then you may now obtain
the switch's IP address, e.g. by invoking a DHCP client. The
secure channel will only be able to connect to the controller after
an IP address has been obtained.
6. The secure channel should connect to the controller within a few
seconds. It may take a little longer if controller discovery is in
use, because the switch must then also obtain its own IP address
and the controller's location via DHCP.
Configuration
=============
Secure operation over SSL
-------------------------
The instructions above set up OpenFlow for operation over a plaintext
TCP connection. Production use of OpenFlow should use SSL[*] to
ensure confidentiality and authenticity of traffic among switches and
controllers. The source must be configured with --enable-ssl=yes to
build with SSL support.
To use SSL with OpenFlow, you must set up a public-key infrastructure
(PKI) including a pair of certificate authorities (CAs), one for
controllers and one for switches. If you have an established PKI,
OpenFlow can use it directly. Otherwise, refer to "Establishing a
Public Key Infrastructure" below.
To configure the controller to listen for SSL connections on port 6633
(the default), invoke it as follows:
# controller -v pssl: --private-key=PRIVKEY --certificate=CERT \
--ca-cert=CACERT
where PRIVKEY is a file containing the controller's private key, CERT
is a file containing the controller CA's certificate for the
controller's public key, and CACERT is a file containing the root
certificate for the switch CA. If, for example, your PKI was created
with the instructions below, then the invocation would look like:
# controller -v pssl: --private-key=ctl-privkey.pem \
--certificate=ctl-cert.pem --ca-cert=pki/switchca/cacert.pem
To configure a switch to connect to a controller running on port 6633
(the default) on host 192.168.1.2 over SSL, invoke ofprotocol as follows:
# ofprotocol -v DATAPATH ssl:192.168.1.2 --private-key=PRIVKEY \
--certificate=CERT --ca-cert=CACERT
where DATAPATH is the datapath to connect to (e.g. nl:0 or
unix:/var/run/dp0.sock), PRIVKEY is a file containing the switch's
private key, CERT is a file containing the switch CA's certificate for
the switch's public key, and CACERT is a file containing the root
certificate for the controller CA. If, for example, your PKI was
created with the instructions below, then the invocation would look
like:
# ofprotocol -v DATAPATH ssl:192.168.1.2 --private-key=sc-privkey.pem \
--certificate=sc-cert.pem --ca-cert=pki/controllerca/cacert.pem
[*] To be specific, OpenFlow uses TLS version 1.0 or later (TLSv1), as
specified by RFC 2246, which is very similar to SSL version 3.0.
TLSv1 was released in January 1999, so all current software and
hardware should implement it.
Establishing a Public Key Infrastructure
----------------------------------------
If you do not have a PKI, the ofp-pki script included with OpenFlow
can help. To create an initial PKI structure, invoke it as:
% ofp-pki init
which will create and populate a new PKI directory. The default
location for the PKI directory depends on how the OpenFlow tree was
configured (to see the configured default, look for the --dir option
description in the output of "ofp-pki --help").
The pki directory contains two important subdirectories. The
controllerca subdirectory contains controller certificate authority
related files, including the following:
- cacert.pem: Root certificate for the controller certificate
authority. This file must be provided to ofprotocol with the
--ca-cert option to enable it to authenticate valid controllers.
- private/cakey.pem: Private signing key for the controller
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
The switchca subdirectory contains switch certificate authority
related files, analogous to those in the controllerca subdirectory:
- cacert.pem: Root certificate for the switch certificate
authority. This file must be provided to the controller program
with the --ca-cert option to enable it to authenticate valid
switches.
- private/cakey.pem: Private signing key for the switch
certificate authority. This file must be kept secret. There is
no need for switches or controllers to have a copy of it.
After you create the initial structure, you can create keys and
certificates for switches and controllers with ofp-pki. To create a
controller private key and certificate in files named ctl-privkey.pem
and ctl-cert.pem, for example, you could run:
% ofp-pki req+sign ctl controller
ctl-privkey.pem and ctl-cert.pem would need to be copied to the
controller for its use at runtime (they could then be deleted from
their original locations). The --private-key and --certificate
options of controller, respectively, would point to these files.
Analogously, to create a switch private key and certificate in files
named sc-privkey.pem and sc-cert.pem, for example, you could run:
% ofp-pki req+sign sc switch
sc-privkey.pem and sc-cert.pem would need to be copied to the switch
for its use at runtime (they could then be deleted from their original
locations). The --private-key and --certificate options,
respectively, of ofprotocol would point to these files.
Bug Reporting
-------------
Please report problems to:
or post them to our online bug tracking system at:
http://www.openflowswitch.org/bugs/openflow