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