6084d463c95e66729b8520b04ae61ea9facae355
[openvswitch] / utilities / ovs-openflowd.8.in
1 .TH ovs\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual"
2 .\" This program's name:
3 .ds PN ovs\-openflowd
4 .\" SSL peer program's name:
5 .ds SN ovs\-controller
6 .
7 .SH NAME
8 ovs\-openflowd \- OpenFlow switch implementation
9 .
10 .SH SYNOPSIS
11 .B ovs\-openflowd
12 [\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR\&...]
13 .
14 .SH DESCRIPTION
15 The \fBovs\-openflowd\fR program implements an OpenFlow switch using a
16 flow-based datapath.  \fBovs\-openflowd\fR connects to one or more
17 OpenFlow controllers over TCP or SSL.
18 .PP
19 For a more powerful alternative to \fBovs\-openflowd\fR, see
20 \fBovs\-vswitchd\fR(8).  Do not run both daemons at the same time.
21 .PP
22 The mandatory \fIdatapath\fR argument argument specifies the local datapath
23 to relay.  It takes one of the following forms:
24 .
25 .so lib/dpif.man
26 .
27 .PP
28 The optional \fIcontroller\fR arguments specify how to connect to the
29 OpenFlow controller or controllers.  Each takes one of the following
30 forms:
31 .
32 .so lib/vconn-active.man
33 .
34 .PP
35 When multiple controllers are configured, \fBovs\-openflowd\fR
36 connects to all of them simultaneously.  OpenFlow 1.0 does not specify
37 how multiple controllers coordinate in interacting with a single
38 switch, so more than one controller should be specified only if the
39 controllers are themselves designed to coordinate with each other.
40 (The Nicira-defined \fBNXT_ROLE\fR OpenFlow vendor extension may be
41 useful for this.)
42 .PP
43 If no \fIcontroller\fR is specified, \fBovs\-openflowd\fR attempts to
44 discover the location of a controller automatically (see below).
45 .
46 .SS "Contacting Controllers"
47 The OpenFlow switch must be able to contact the OpenFlow controllers
48 over the network.  It can do so in one of two ways:
49 .
50 .IP out-of-band
51 In this configuration, OpenFlow traffic uses a network separate from
52 the data traffic that it controls, that is, the switch does not use
53 any of the network devices added to the datapath with \fBovs\-dpctl
54 add\-if\fR in its communication with the controller.
55 .IP
56 To use \fBovs\-openflowd\fR in a network with out-of-band control, specify
57 \fB\-\-out\-of\-band\fR on the \fBovs\-openflowd\fR command line.  The control
58 network must be configured separately, before or after \fBovs\-openflowd\fR
59 is started.
60 .
61 .IP in-band
62 In this configuration, a single network is used for OpenFlow traffic
63 and other data traffic, that is, the switch contacts the controller
64 over one of the network devices added to the datapath with \fBovs\-dpctl
65 add\-if\fR.  This configuration is often more convenient than
66 out-of-band control, because it is not necessary to maintain two
67 independent networks.
68 .IP
69 In-band control is the default for \fBovs\-openflowd\fR, so no special
70 command-line option is required.
71 .IP
72 With in-band control, the location of the controller can be configured
73 manually or discovered automatically:
74 .
75 .RS
76 .IP "controller discovery"
77 To make \fBovs\-openflowd\fR discover the location of the controller
78 automatically, do not specify a controller on the \fBovs\-openflowd\fR
79 command line.
80 .IP
81 In this mode, \fBovs\-openflowd\fR will broadcast a DHCP request with vendor
82 class identifier \fBOpenFlow\fR across the network devices added to
83 the datapath with \fBovs\-dpctl add\-if\fR.  It will accept any valid DHCP
84 reply that has the same vendor class identifier and includes a
85 vendor-specific option with code 1 whose contents are a string
86 specifying the location of the controller in the same format used on
87 the \fBovs\-openflowd\fR command line (e.g. \fBssl:192.168.0.1\fR).
88 .IP
89 The DHCP reply may also, optionally, include a vendor-specific option
90 with code 2 whose contents are a string specifying the URI to the base
91 of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
92 This URI is used only for bootstrapping the OpenFlow PKI at initial
93 switch setup; \fBovs\-openflowd\fR does not use it at all.
94 .IP
95 The following ISC DHCP server configuration file assigns the IP
96 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
97 that follow the switch protocol and addresses 192.168.0.1 through
98 192.168.0.10 to all other DHCP clients:
99 .IP
100 default\-lease\-time 600;
101 .br
102 max\-lease\-time 7200;
103 .br
104 option space openflow;
105 .br
106 option openflow.controller\-vconn code 1 = text;
107 .br
108 option openflow.pki\-uri code 2 = text;
109 .br
110 class "OpenFlow" {
111 .br
112   match if option vendor\-class\-identifier = "OpenFlow";
113 .br
114   vendor\-option\-space openflow;
115 .br
116   option openflow.controller\-vconn "tcp:192.168.0.10";
117 .br
118   option openflow.pki\-uri "http://192.168.0.10/openflow/pki";
119 .br
120   option vendor\-class\-identifier "OpenFlow";
121 .br
122 }
123 .br
124 subnet 192.168.0.0 netmask 255.255.255.0 {
125 .br
126     pool {
127 .br
128         allow members of "OpenFlow";
129 .br
130         range 192.168.0.20 192.168.0.30;
131 .br
132     }
133 .br
134     pool {
135 .br
136         deny members of "OpenFlow";
137 .br
138         range 192.168.0.1 192.168.0.10;
139 .br
140     }
141 .br
142 }
143 .br
144 .
145 .IP "manual configuration"
146 To configure in-band control manually, specify the location of the
147 controller on the \fBovs\-openflowd\fR command line as the \fIcontroller\fR
148 argument.  You must also configure the network device for the OpenFlow
149 ``local port'' to allow \fBovs\-openflowd\fR to connect to that controller.
150 The OpenFlow local port is a virtual network port that \fBovs\-openflowd\fR
151 bridges to the physical switch ports.  The name of the local port for
152 a given \fIdatapath\fR may be seen by running \fBovs\-dpctl show
153 \fIdatapath\fR; the local port is listed as port 0 in \fBshow\fR's
154 output.
155 .
156 .IP
157 Before \fBovs\-openflowd\fR starts, the local port network device is not
158 bridged to any physical network, so the next step depends on whether
159 connectivity is required to configure the device's IP address.  If the
160 switch has a static IP address, you may configure its IP address now
161 with a command such as 
162 .B ifconfig of0 192.168.1.1
163 and then invoke \fBovs\-openflowd\fR.
164 .IP
165 On the other hand, if the switch does not have a static IP address,
166 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
167 will not be able to contact the DHCP server until the OpenFlow switch
168 has started up.  Thus, start \fBovs\-openflowd\fR without configuring
169 the local port network device, and start the DHCP client afterward.
170 .RE
171 .
172 .SH OPTIONS
173 .SS "OpenFlow Options"
174 .TP
175 \fB\-\-datapath\-id=\fIdpid\fR
176 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits
177 and may not be all-zero,
178 as the datapath ID that the switch will use to identify itself to
179 OpenFlow controllers.
180 .IP
181 If this option is omitted, the default datapath ID is taken from the
182 Ethernet address of the datapath's local port (which is typically
183 randomly generated) in the lower 48 bits and zeros in the upper 16.
184 .
185 .TP
186 \fB\-\-mfr\-desc=\fIdesc\fR
187 Set the description of the switch's manufacturer to \fIdesc\fR, which
188 may contain up to 255 ASCII characters.
189 .
190 .TP
191 \fB\-\-hw\-desc=\fIdesc\fR
192 Set the description of the switch's hardware revision to \fIdesc\fR, which
193 may contain up to 255 ASCII characters.
194 .
195 .TP
196 \fB\-\-sw\-desc=\fIdesc\fR
197 Set the description of the switch's software revision to \fIdesc\fR, which
198 may contain up to 255 ASCII characters.
199 .
200 .TP
201 \fB\-\-serial\-desc=\fIdesc\fR
202 Set the description of the switch's serial number to \fIdesc\fR, which
203 may contain up to 31 ASCII characters.
204 .
205 .TP
206 \fB\-\-dp\-desc=\fIdesc\fR
207 Set the description of the datapath to \fIdesc\fR, which may contain up to
208 255 ASCII characters.  Note that this field is intended for debugging
209 purposes and is not guaranteed to be unique and should not be used as
210 the primary identifier of the datapath.
211 .
212 .SS "Controller Discovery Options"
213 .TP
214 \fB\-\-accept\-vconn=\fIregex\fR
215 When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
216 the Controller\fR, above, for more information about controller
217 discovery), it validates the controller location obtained via DHCP
218 with a POSIX extended regular expression.  Only controllers whose
219 names match the regular expression will be accepted.
220 .IP
221 The default regular expression is \fBssl:.*\fR (meaning that only SSL
222 controller connections will be accepted) when any of the SSL
223 configuration options \fB\-\-private\-key\fR, \fB\-\-certificate\fR, or
224 \fB\-\-ca\-cert\fR is specified.  The default is \fB^tcp:.*\fR otherwise
225 (meaning that only TCP controller connections will be accepted).
226 .IP
227 The \fIregex\fR is implicitly anchored at the beginning of the
228 controller location string, as if it begins with \fB^\fR.
229 .IP
230 When controller discovery is not performed, this option has no effect.
231 .
232 .TP
233 \fB\-\-no\-resolv\-conf\fR
234 When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
235 the Controller\fR, above, for more information about controller
236 discovery), by default it overwrites the system's
237 \fB/etc/resolv.conf\fR with domain information and DNS servers
238 obtained via DHCP.  If the location of the controller is specified
239 using a hostname, rather than an IP address, and the network's DNS
240 servers ever change, this behavior is essential.  But because it also
241 interferes with any administrator or process that manages
242 \fB/etc/resolv.conf\fR, when this option is specified, \fBovs\-openflowd\fR
243 will not modify \fB/etc/resolv.conf\fR.
244 .IP
245 \fBovs\-openflowd\fR will only modify \fBresolv.conf\fR if the DHCP response
246 that it receives specifies one or more DNS servers.
247 .IP
248 When controller discovery is not performed, this option has no effect.
249 .
250 .SS "Networking Options"
251 .TP
252 \fB\-\-datapath\-id=\fIdpid\fR
253 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits,
254 as the datapath ID that the switch will use to identify itself to the
255 OpenFlow controller.
256 .IP
257 If this option is omitted, the default datapath ID is taken from the
258 Ethernet address of the datapath's local port (which is typically
259 randomly generated) in the lower 48 bits and zeros in the upper 16.
260 .
261 .TP
262 \fB\-\-fail=\fR[\fBstandalone\fR|\fBsecure\fR]
263 The controller is, ordinarily, responsible for setting up all flows on
264 the OpenFlow switch.  Thus, if the connection to the controller fails,
265 no new network connections can be set up.  If the connection to the
266 controller stays down long enough, no packets can pass through the
267 switch at all.
268 .IP
269 If this option is set to \fBstandalone\fR (the default),
270 \fBovs\-openflowd\fR will
271 take over responsibility for setting up flows in the local datapath
272 when no message has been received from the controller for three times
273 the inactivity probe interval (see below), or 45 seconds by default.
274 In this ``fail open'' mode, \fBovs\-openflowd\fR causes the datapath to act
275 like an ordinary MAC-learning switch.  \fBovs\-openflowd\fR will continue to
276 retry connection to the controller in the background and, when the
277 connection succeeds, it discontinues its standalone switching behavior.
278 .IP
279 If this option is set to \fBsecure\fR, then \fBovs\-openflowd\fR will not
280 set up flows on its own when the controller connection fails.
281 .
282 .TP
283 \fB\-\-inactivity\-probe=\fIsecs\fR
284 When the OpenFlow switch is connected to the controller, the
285 switch waits for a message to be received from the controller for
286 \fIsecs\fR seconds before it sends a inactivity probe to the
287 controller.  After sending the inactivity probe, if no response is
288 received for an additional \fIsecs\fR seconds, the switch
289 assumes that the connection has been broken and attempts to reconnect.
290 The default and the minimum value are both 5 seconds.
291 .IP
292 When fail-open mode is configured, changing the inactivity probe
293 interval also changes the interval before entering fail-open mode (see
294 above).
295 .
296 .TP
297 \fB\-\-max\-idle=\fIsecs\fR|\fBpermanent\fR
298 Sets \fIsecs\fR as the number of seconds that a flow set up by the
299 OpenFlow switch will remain in the switch's flow table without any
300 matching packets being seen.  If \fBpermanent\fR is specified, which
301 is not recommended, flows set up by the switch will never
302 expire.  The default is 15 seconds.
303 .IP
304 Most flows are set up by the OpenFlow controller, not by the
305 switch.  This option affects only the following flows, which the
306 OpenFlow switch sets up itself:
307 .
308 .RS
309 .IP \(bu
310 When \fB\-\-fail=open\fR is specified, flows set up when the
311 switch has not been able to contact the controller for the configured
312 fail-open delay.
313 .
314 .IP \(bu
315 When in-band control is in use, flows set up to bootstrap contacting
316 the controller (see \fBContacting the Controller\fR, above, for
317 more information about in-band control).
318 .RE
319 .
320 .IP
321 As a result, when both \fB\-\-fail=secure\fR and \fB\-\-out\-of\-band\fR are
322 specified, this option has no effect.
323 .
324 .TP
325 \fB\-\-max\-backoff=\fIsecs\fR
326 Sets the maximum time between attempts to connect to the controller to
327 \fIsecs\fR, which must be at least 1.  The actual interval between
328 connection attempts starts at 1 second and doubles on each failing
329 attempt until it reaches the maximum.  The default maximum backoff
330 time is 8 seconds.
331 .
332 .TP
333 \fB\-l\fR, \fB\-\-listen=\fImethod\fR
334 By default, the switch listens for OpenFlow management connections on a
335 Unix domain socket named \fB@RUNDIR@/\fIdatapath\fB.mgmt\fR.  This socket 
336 can be used to perform local OpenFlow monitoring and administration with
337 tools such as \fBovs\-ofctl\fR.  
338 .IP
339 This option may be used to override the default listener.  The \fImethod\fR
340 must be given as one of the passive OpenFlow connection methods listed
341 below.  This option may be specified multiple times to listen to
342 multiple connection methods.  If a single \fImethod\fR of \fBnone\fR is
343 used, no listeners will be created.
344 .
345 .RS
346 .so lib/vconn-passive.man
347 .RE
348 .
349 .TP
350 \fB\-\-snoop=\fImethod\fR
351 Configures the switch to additionally listen for incoming OpenFlow
352 connections for controller connection snooping.  The \fImethod\fR must
353 be given as one of the passive OpenFlow connection methods listed
354 under the \fB\-\-listen\fR option above.  This option may be specified
355 multiple times to listen to multiple connection methods.
356 .IP
357 If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on
358 \fB\-\-snoop\fR, it will display all the OpenFlow messages traveling
359 between the switch and its controller on the primary OpenFlow
360 connection.  This can be useful for debugging switch and controller
361 problems.
362 .
363 .TP
364 \fB\-\-in\-band\fR, \fB\-\-out\-of\-band\fR
365 Configures \fBovs\-openflowd\fR to operate in in-band or out-of-band control
366 mode (see \fBContacting the Controller\fR above).  When neither option
367 is given, the default is in-band control.
368 .
369 .TP
370 \fB\-\-netflow=\fIip\fB:\fIport\fR
371 Configures the given UDP \fIport\fR on the specified IP \fIip\fR as
372 a recipient of NetFlow messages for expired flows.  The \fIip\fR must
373 be specified numerically, not as a DNS name.
374 .IP
375 This option may be specified multiple times to configure additional
376 NetFlow collectors.
377 .
378 .SS "Rate-Limiting Options"
379 .
380 These options configure how the switch applies a ``token bucket'' to
381 limit the rate at which packets in unknown flows are forwarded to an
382 OpenFlow controller for flow-setup processing.  This feature prevents
383 a single OpenFlow switch from overwhelming a controller.
384 .
385 .TP
386 \fB\-\-rate\-limit\fR[\fB=\fIrate\fR]
387 .
388 Limits the maximum rate at which packets will be forwarded to the
389 OpenFlow controller to \fIrate\fR packets per second.  If \fIrate\fR
390 is not specified then the default of 1,000 packets per second is used.
391 .IP
392 If \fB\-\-rate\-limit\fR is not used, then the switch does not limit the
393 rate at which packets are forwarded to the controller.
394 .
395 .TP
396 \fB\-\-burst\-limit=\fIburst\fR
397 .
398 Sets the maximum number of unused packet credits that the switch will
399 allow to accumulate during time in which no packets are being
400 forwarded to the OpenFlow controller to \fIburst\fR (measured in
401 packets).  The default \fIburst\fR is one-quarter of the \fIrate\fR
402 specified on \fB\-\-rate\-limit\fR.
403 .
404 This option takes effect only when \fB\-\-rate\-limit\fR is also specified.
405 .
406 .SS "Datapath Options"
407 .
408 .IP "\fB\-\-ports=\fIport\fR[\fB,\fIport\fR...]"
409 Ordinarily, \fBovs\-openflowd\fR expects the administrator to create
410 the specified \fIdatapath\fR and add ports to it externally with a
411 utility such as \fBovs\-dpctl\fR.  However, the userspace switch
412 datapath is implemented inside \fBovs\-openflowd\fR itself and does
413 not (currently) have any external interface for \fBovs\-dpctl\fR to
414 access.  As a stopgap measure, this option specifies one or more ports
415 to add to the datapath at \fBovs\-openflowd\fR startup time.  Multiple
416 ports may be specified as a comma-separated list or by specifying
417 \fB\-\-ports\fR multiple times.
418 .IP
419 See \fBINSTALL.userspace\fR for more information about userspace
420 switching.
421 .
422 .SS "Daemon Options"
423 .so lib/daemon.man
424 .
425 .SS "Public Key Infrastructure Options"
426 .so lib/ssl.man
427 .so lib/ssl-bootstrap.man
428 .
429 .SS "Logging Options"
430 .so lib/vlog.man
431 .SS "Other Options"
432 .so lib/unixctl.man
433 .so lib/common.man
434 .so lib/leak-checker.man
435 .
436 .SH "RUNTIME MANAGEMENT COMMANDS"
437 \fBovs\-appctl\fR(8) can send commands to a running
438 \fBovs\-openflowd\fR process.  The currently supported commands are
439 described below.
440 .so lib/vlog-unixctl.man
441 .
442 .SH "SEE ALSO"
443 .
444 .BR ovs\-appctl (8),
445 .BR ovs\-controller (8),
446 .BR ovs\-discover (8),
447 .BR ovs\-dpctl (8),
448 .BR ovs\-ofctl (8),
449 .BR ovs\-pki (8)