]>
Commit | Line | Data |
---|---|---|
064af421 BP |
1 | .TH secchan 8 "March 2009" "Open vSwitch" "Open vSwitch Manual" |
2 | .ds PN secchan | |
3 | ||
4 | .SH NAME | |
5 | secchan \- OpenFlow switch implementation | |
6 | ||
7 | .SH SYNOPSIS | |
8 | .B secchan | |
9 | [\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR] | |
10 | ||
11 | .SH DESCRIPTION | |
12 | The \fBsecchan\fR program implements an OpenFlow switch using a | |
13 | flow-based datapath. \fBsecchan\fR connects to an OpenFlow controller | |
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 | |
26 | .TP | |
27 | \fBssl:\fIhost\fR[\fB:\fIport\fR] | |
28 | The specified SSL \fIport\fR (default: 6633) on the given remote | |
29 | \fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and | |
30 | \fB--ca-cert\fR options are mandatory when this form is used. | |
31 | ||
32 | .TP | |
33 | \fBtcp:\fIhost\fR[\fB:\fIport\fR] | |
34 | The specified TCP \fIport\fR (default: 6633) on the given remote | |
35 | \fIhost\fR. | |
36 | ||
37 | .TP | |
38 | \fBunix:\fIfile\fR | |
39 | The Unix domain server socket named \fIfile\fR. | |
40 | .RE | |
41 | ||
42 | .PP | |
43 | If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the | |
44 | location of the controller automatically (see below). | |
45 | ||
46 | .SS "Contacting the Controller" | |
47 | The OpenFlow switch must be able to contact the OpenFlow controller | |
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 | ||
56 | To use \fBsecchan\fR in a network with out-of-band control, specify | |
57 | \fB--out-of-band\fR on the \fBsecchan\fR command line. The control | |
58 | network must be configured separately, before or after \fBsecchan\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 | ||
69 | In-band control is the default for \fBsecchan\fR, so no special | |
70 | command-line option is required. | |
71 | ||
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 \fBsecchan\fR discover the location of the controller | |
78 | automatically, do not specify the location of the controller on the | |
79 | \fBsecchan\fR command line. | |
80 | ||
81 | In this mode, \fBsecchan\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 \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR). | |
88 | ||
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; \fBsecchan\fR does not use it at all. | |
94 | ||
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 | ||
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 \fBsecchan\fR command line as the \fIcontroller\fR | |
148 | argument. You must also configure the network device for the OpenFlow | |
149 | ``local port'' to allow \fBsecchan\fR to connect to that controller. | |
150 | The OpenFlow local port is a virtual network port that \fBsecchan\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 \fBsecchan\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 \fBsecchan\fR. | |
164 | ||
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 secure channel | |
168 | has started up. Thus, start \fBsecchan\fR without configuring | |
169 | the local port network device, and start the DHCP client afterward. | |
170 | .RE | |
171 | ||
172 | .SH OPTIONS | |
173 | .SS "Controller Discovery Options" | |
174 | .TP | |
175 | \fB--accept-vconn=\fIregex\fR | |
176 | When \fBsecchan\fR performs controller discovery (see \fBContacting | |
177 | the Controller\fR, above, for more information about controller | |
178 | discovery), it validates the controller location obtained via DHCP | |
179 | with a POSIX extended regular expression. Only controllers whose | |
180 | names match the regular expression will be accepted. | |
181 | ||
182 | The default regular expression is \fBssl:.*\fR (meaning that only SSL | |
183 | controller connections will be accepted) when any of the SSL | |
184 | configuration options \fB--private-key\fR, \fB--certificate\fR, or | |
185 | \fB--ca-cert\fR is specified. The default is \fB.*\fR otherwise | |
186 | (meaning that any controller will be accepted). | |
187 | ||
188 | The \fIregex\fR is implicitly anchored at the beginning of the | |
189 | controller location string, as if it begins with \fB^\fR. | |
190 | ||
191 | When controller discovery is not performed, this option has no effect. | |
192 | ||
193 | .TP | |
194 | \fB--no-resolv-conf\fR | |
195 | When \fBsecchan\fR performs controller discovery (see \fBContacting | |
196 | the Controller\fR, above, for more information about controller | |
197 | discovery), by default it overwrites the system's | |
198 | \fB/etc/resolv.conf\fR with domain information and DNS servers | |
199 | obtained via DHCP. If the location of the controller is specified | |
200 | using a hostname, rather than an IP address, and the network's DNS | |
201 | servers ever change, this behavior is essential. But because it also | |
202 | interferes with any administrator or process that manages | |
203 | \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR | |
204 | will not modify \fB/etc/resolv.conf\fR. | |
205 | ||
206 | \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response | |
207 | that it receives specifies one or more DNS servers. | |
208 | ||
209 | When controller discovery is not performed, this option has no effect. | |
210 | ||
211 | .SS "Networking Options" | |
212 | .TP | |
213 | \fB--datapath-id=\fIdpid\fR | |
214 | Sets \fIdpid\fR, which must consist of exactly 12 hexadecimal digits, | |
215 | as the datapath ID that the switch will use to identify itself to the | |
216 | OpenFlow controller. | |
217 | ||
218 | If this option is omitted, the default datapath ID is taken from the | |
219 | Ethernet address of the datapath's local port (which is typically | |
220 | randomly generated). | |
221 | ||
222 | .TP | |
223 | \fB--mgmt-id=\fImgmtid\fR | |
224 | Sets \fImgmtid\fR, which must consist of exactly 12 hexadecimal | |
225 | digits, as the switch's management ID. | |
226 | ||
227 | If this option is omitted, the management ID defaults to 0, signaling | |
228 | to the controller that management is supported but not configured. | |
229 | ||
230 | .TP | |
231 | \fB--fail=\fR[\fBopen\fR|\fBclosed\fR] | |
232 | The controller is, ordinarily, responsible for setting up all flows on | |
233 | the OpenFlow switch. Thus, if the connection to the controller fails, | |
234 | no new network connections can be set up. If the connection to the | |
235 | controller stays down long enough, no packets can pass through the | |
236 | switch at all. | |
237 | ||
238 | If this option is set to \fBopen\fR (the default), \fBsecchan\fR will | |
239 | take over responsibility for setting up flows in the local datapath | |
240 | when no message has been received from the controller for three times | |
241 | the inactivity probe interval (see below), or 45 seconds by default. | |
242 | In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act | |
243 | like an ordinary MAC-learning switch. \fBsecchan\fR will continue to | |
244 | retry connection to the controller in the background and, when the | |
245 | connection succeeds, it discontinues its fail-open behavior. | |
246 | ||
247 | If this option is set to \fBclosed\fR, then \fBsecchan\fR will not | |
248 | set up flows on its own when the controller connection fails. | |
249 | ||
250 | .TP | |
251 | \fB--inactivity-probe=\fIsecs\fR | |
252 | When the secure channel is connected to the controller, the secure | |
253 | channel waits for a message to be received from the controller for | |
254 | \fIsecs\fR seconds before it sends a inactivity probe to the | |
255 | controller. After sending the inactivity probe, if no response is | |
256 | received for an additional \fIsecs\fR seconds, the secure channel | |
257 | assumes that the connection has been broken and attempts to reconnect. | |
258 | The default is 15 seconds, and the minimum value is 5 seconds. | |
259 | ||
260 | When fail-open mode is configured, changing the inactivity probe | |
261 | interval also changes the interval before entering fail-open mode (see | |
262 | above). | |
263 | ||
264 | .TP | |
265 | \fB--max-idle=\fIsecs\fR|\fBpermanent\fR | |
266 | Sets \fIsecs\fR as the number of seconds that a flow set up by the | |
267 | secure channel will remain in the switch's flow table without any | |
268 | matching packets being seen. If \fBpermanent\fR is specified, which | |
269 | is not recommended, flows set up by the secure channel will never | |
270 | expire. The default is 15 seconds. | |
271 | ||
272 | Most flows are set up by the OpenFlow controller, not by the secure | |
273 | channel. This option affects only the following flows, which the | |
274 | secure channel sets up itself: | |
275 | ||
276 | .RS | |
277 | .IP \(bu | |
278 | When \fB--fail=open\fR is specified, flows set up when the secure | |
279 | channel has not been able to contact the controller for the configured | |
280 | fail-open delay. | |
281 | ||
282 | .IP \(bu | |
283 | When in-band control is in use, flows set up to bootstrap contacting | |
284 | the controller (see \fBContacting the Controller\fR, above, for | |
285 | more information about in-band control). | |
286 | .RE | |
287 | ||
288 | .IP | |
289 | As a result, when both \fB--fail=closed\fR and \fB--out-of-band\fR are | |
290 | specified, this option has no effect. | |
291 | ||
292 | .TP | |
293 | \fB--max-backoff=\fIsecs\fR | |
294 | Sets the maximum time between attempts to connect to the controller to | |
295 | \fIsecs\fR, which must be at least 1. The actual interval between | |
296 | connection attempts starts at 1 second and doubles on each failing | |
297 | attempt until it reaches the maximum. The default maximum backoff | |
298 | time is 15 seconds. | |
299 | ||
300 | .TP | |
301 | \fB-l\fR, \fB--listen=\fImethod\fR | |
302 | Configures the switch to additionally listen for incoming OpenFlow | |
303 | connections for switch management with \fBovs\-ofctl\fR. The \fImethod\fR | |
304 | must be given as one of the passive OpenFlow connection methods listed | |
305 | below. This option may be specified multiple times to listen to | |
306 | multiple connection methods. | |
307 | ||
308 | .RS | |
309 | .TP | |
310 | \fBpssl:\fR[\fIport\fR] | |
311 | Listens for SSL connections on \fIport\fR (default: 6633). The | |
312 | \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options | |
313 | are mandatory when this form is used. | |
314 | ||
315 | .TP | |
316 | \fBptcp:\fR[\fIport\fR] | |
317 | Listens for TCP connections on \fIport\fR (default: 6633). | |
318 | ||
319 | .TP | |
320 | \fBpunix:\fIfile\fR | |
321 | Listens for connections on Unix domain server socket named \fIfile\fR. | |
322 | .RE | |
323 | ||
324 | .TP | |
325 | \fB--snoop=\fImethod\fR | |
326 | Configures the switch to additionally listen for incoming OpenFlow | |
327 | connections for controller connection snooping. The \fImethod\fR must | |
328 | be given as one of the passive OpenFlow connection methods listed | |
329 | under the \fB--listen\fR option above. This option may be specified | |
330 | multiple times to listen to multiple connection methods. | |
331 | ||
332 | If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on | |
333 | \fB--snoop\fR, it will display all the OpenFlow messages traveling | |
334 | between the switch and its controller on the primary OpenFlow | |
335 | connection. This can be useful for debugging switch and controller | |
336 | problems. | |
337 | ||
338 | .TP | |
339 | \fB--in-band\fR, \fB--out-of-band\fR | |
340 | Configures \fBsecchan\fR to operate in in-band or out-of-band control | |
341 | mode (see \fBContacting the Controller\fR above). When neither option | |
342 | is given, the default is in-band control. | |
343 | ||
344 | .TP | |
345 | \fB--netflow=\fIhost\fB:\fIport\fR | |
346 | Configures the given UDP \fIport\fR on the specified IP \fIhost\fR as | |
347 | a recipient of NetFlow messages for expired flows. | |
348 | ||
349 | This option may be specified multiple times to configure additional | |
350 | NetFlow collectors. | |
351 | ||
352 | .SS "Rate-Limiting Options" | |
353 | ||
354 | These options configure how the switch applies a ``token bucket'' to | |
355 | limit the rate at which packets in unknown flows are forwarded to an | |
356 | OpenFlow controller for flow-setup processing. This feature prevents | |
357 | a single OpenFlow switch from overwhelming a controller. | |
358 | ||
359 | .TP | |
360 | \fB--rate-limit\fR[\fB=\fIrate\fR] | |
361 | . | |
362 | Limits the maximum rate at which packets will be forwarded to the | |
363 | OpenFlow controller to \fIrate\fR packets per second. If \fIrate\fR | |
364 | is not specified then the default of 1,000 packets per second is used. | |
365 | ||
366 | If \fB--rate-limit\fR is not used, then the switch does not limit the | |
367 | rate at which packets are forwarded to the controller. | |
368 | ||
369 | .TP | |
370 | \fB--burst-limit=\fIburst\fR | |
371 | . | |
372 | Sets the maximum number of unused packet credits that the switch will | |
373 | allow to accumulate during time in which no packets are being | |
374 | forwarded to the OpenFlow controller to \fIburst\fR (measured in | |
375 | packets). The default \fIburst\fR is one-quarter of the \fIrate\fR | |
376 | specified on \fB--rate-limit\fR. | |
377 | ||
378 | This option takes effect only when \fB--rate-limit\fR is also specified. | |
379 | ||
380 | .SS "Remote Command Execution Options" | |
381 | ||
382 | .TP | |
383 | \fB--command-acl=\fR[\fB!\fR]\fIglob\fR[\fB,\fR[\fB!\fR]\fIglob\fR...] | |
384 | Configures the commands that remote OpenFlow connections are allowed | |
385 | to invoke using (e.g.) \fBovs\-ofctl execute\fR. The argument is a | |
386 | comma-separated sequence of shell glob patterns. A glob pattern | |
387 | specified without a leading \fB!\fR is a ``whitelist'' that specifies | |
388 | a set of commands that are that may be invoked, whereas a pattern that | |
389 | does begin with \fB!\fR is a ``blacklist'' that specifies commands | |
390 | that may not be invoked. To be permitted, a command name must be | |
391 | whitelisted and must not be blacklisted; | |
392 | e.g. \fB--command-acl=up*,!upgrade\fR would allow any command whose name | |
393 | begins with \fBup\fR except for the command named \fBupgrade\fR. | |
394 | Command names that include characters other than upper- and lower-case | |
395 | English letters, digits, and the underscore and hyphen characters are | |
396 | unconditionally disallowed. | |
397 | ||
398 | When the whitelist and blacklist permit a command name, \fBsecchan\fR | |
399 | looks for a program with the same name as the command in the commands | |
400 | directory (see below). Other directories are not searched. | |
401 | ||
402 | .TP | |
403 | \fB--command-dir=\fIdirectory\fR | |
404 | Sets the directory searched for remote command execution to | |
405 | \fBdirectory\fR. The default directory is | |
406 | \fB@pkgdatadir@/commands\fR. | |
407 | ||
408 | .SS "Daemon Options" | |
409 | .so lib/daemon.man | |
410 | ||
411 | .SS "Public Key Infrastructure Options" | |
412 | ||
413 | .TP | |
414 | \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR | |
415 | Specifies a PEM file containing the private key used as the switch's | |
416 | identity for SSL connections to the controller. | |
417 | ||
418 | .TP | |
419 | \fB-c\fR, \fB--certificate=\fIcert.pem\fR | |
420 | Specifies a PEM file containing a certificate, signed by the | |
421 | controller's certificate authority (CA), that certifies the switch's | |
422 | private key to identify a trustworthy switch. | |
423 | ||
424 | .TP | |
425 | \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR | |
426 | Specifies a PEM file containing the CA certificate used to verify that | |
427 | the switch is connected to a trustworthy controller. | |
428 | ||
429 | .TP | |
430 | \fB--bootstrap-ca-cert=\fIcacert.pem\fR | |
431 | When \fIcacert.pem\fR exists, this option has the same effect as | |
432 | \fB-C\fR or \fB--ca-cert\fR. If it does not exist, then \fBsecchan\fR | |
433 | will attempt to obtain the CA certificate from the controller on its | |
434 | first SSL connection and save it to the named PEM file. If it is | |
435 | successful, it will immediately drop the connection and reconnect, and | |
436 | from then on all SSL connections must be authenticated by a | |
437 | certificate signed by the CA certificate thus obtained. | |
438 | ||
439 | \fBThis option exposes the SSL connection to a man-in-the-middle | |
440 | attack obtaining the initial CA certificate\fR, but it may be useful | |
441 | for bootstrapping. | |
442 | ||
443 | This option is only useful if the controller sends its CA certificate | |
444 | as part of the SSL certificate chain. The SSL protocol does not | |
445 | require the controller to send the CA certificate, but | |
446 | \fBcontroller\fR(8) can be configured to do so with the | |
447 | \fB--peer-ca-cert\fR option. | |
448 | ||
449 | .SS "Logging Options" | |
450 | .so lib/vlog.man | |
451 | .SS "Other Options" | |
452 | .so lib/common.man | |
453 | .so lib/leak-checker.man | |
454 | ||
455 | .SH "SEE ALSO" | |
456 | ||
457 | .BR ovs\-appctl (8), | |
458 | .BR ovs\-controller (8), | |
459 | .BR ovs\-discover (8), | |
460 | .BR ovs\-dpctl (8), | |
461 | .BR ovs\-ofctl (8), | |
462 | .BR ovs\-pki (8), | |
463 | .BR ovs\-vswitchd.conf (5) |