1 .TH secchan 8 "October 2008" "OpenFlow" "OpenFlow Manual"
4 secchan \- secure channel connecting an OpenFlow datapath to a controller
8 [\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR]
11 The \fBsecchan\fR program sets up a secure channel between a local
12 OpenFlow datapath and a remote controller. \fBsecchan\fR connects to
13 the local datapath over Netlink and to the controller over TCP or SSL,
14 and then forwards OpenFlow messages from one endpoint to the other.
16 The mandatory \fIdatapath\fR argument argument specifies the local datapath
17 to relay. It takes one of the following forms:
21 Attach to the local kernel-based datapath over the Netlink protocol.
22 The \fIdp_idx\fR argument is the number of a datapath created with
27 Attach to the userspace datapath implemented by \fBudatapath\fR(8).
28 The \fIfile\fR argument must the same one specified on the
29 \fBudatapath\fR command line.
32 The optional \fIcontroller\fR argument specifies how to connect to
33 the OpenFlow controller. It takes one of the following forms:
36 \fBssl:\fIhost\fR[\fB:\fIport\fR]
37 The specified SSL \fIport\fR (default: 6633) on the given remote
38 \fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
39 \fB--ca-cert\fR options are mandatory when this form is used.
42 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
43 The specified TCP \fIport\fR (default: 6633) on the given remote
48 The Unix domain server socket named \fIfile\fR.
51 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
52 location of the controller automatically (see below).
54 .SH "CONTACTING THE CONTROLLER"
55 The OpenFlow switch must be able to contact the OpenFlow controller
56 over the network. It can do so in one of two ways:
59 In this configuration, OpenFlow traffic uses a network separate from
60 the data traffic that it controls, that is, the switch does not use
61 any of the network devices added to the datapath with \fBdpctl
62 addif\fR in its communication with the controller.
64 To use \fBsecchan\fR in a network with out-of-band control, specify
65 \fB--out-of-band\fR on the \fBsecchan\fR command line. The control
66 network must be configured separately, before or after \fBsecchan\fR
70 In this configuration, a single network is used for OpenFlow traffic
71 and other data traffic, that is, the switch contacts the controller
72 over one of the network devices added to the datapath with \fBdpctl
73 addif\fR. This configuration is often more convenient than
74 out-of-band control, because it is not necessary to maintain two
77 In-band control is the default for \fBsecchan\fR, so no special
78 command-line option is required.
80 With in-band control, the location of the controller can be configured
81 manually or discovered automatically:
84 .IP "controller discovery"
85 To make \fBsecchan\fR discover the location of the controller
86 automatically, do not specify the location of the controller on the
87 \fBsecchan\fR command line.
89 In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
90 class identifier \fBOpenFlow\fR across the network devices added to
91 the datapath with \fBdpctl addif\fR. It will accept any valid DHCP
92 reply that has the same vendor class identifier and includes a
93 vendor-specific option with code 1 whose contents are a string
94 specifying the location of the controller in the same format used on
95 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
97 The DHCP reply may also, optionally, include a vendor-specific option
98 with code 2 whose contents are a string specifying the URI to the base
99 of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
100 This URI is used only for bootstrapping the OpenFlow PKI at initial
101 switch setup; \fBsecchan\fR does not use it at all.
103 The following ISC DHCP server configuration file assigns the IP
104 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
105 that follow the switch protocol and addresses 192.168.0.1 through
106 192.168.0.10 to all other DHCP clients:
108 default-lease-time 600;
112 option space openflow;
114 option openflow.controller-vconn code 1 = text;
116 option openflow.pki-uri code 2 = text;
120 match if option vendor-class-identifier = "OpenFlow";
122 vendor-option-space openflow;
124 option openflow.controller-vconn "tcp:192.168.0.10";
126 option openflow.pki-uri "http://192.168.0.10/openflow/pki";
128 option vendor-class-identifier "OpenFlow";
132 subnet 192.168.0.0 netmask 255.255.255.0 {
136 allow members of "OpenFlow";
138 range 192.168.0.20 192.168.0.30;
144 deny members of "OpenFlow";
146 range 192.168.0.1 192.168.0.10;
153 .IP "manual configuration"
154 To configure in-band control manually, specify the location of the
155 controller on the \fBsecchan\fR command line as the \fIcontroller\fR
156 argument. You must also configure the network device for the OpenFlow
157 ``local port'' to allow \fBsecchan\fR to connect to that controller.
158 The OpenFlow local port is a virtual network port that \fBsecchan\fR
159 bridges to the physical switch ports. Its network device name depends
160 on the \fIdatapath\fR specified on the \fBsecchan\fR command line:
165 The local port network device for \fBnl:\fIdp_idx\fR is always named
166 \fBof\fIdp_idx\fR, i.e. the device for \fBnl:0\fR is \fBof0\fR.
170 The local port network device name may be specified on the
171 \fBudatapath\fR command line, using the \fB--local-port\fR option. It
176 Before \fBsecchan\fR starts, the local port network device is not
177 bridged to any physical network, so the next step depends on whether
178 connectivity is required to configure the device's IP address. If the
179 switch has a static IP address, you may configure its IP address now
180 with a command such as:
183 ifconfig of0 192.168.1.1
186 and then invoke \fBsecchan\fR.
188 On the other hand, if the switch does not have a static IP address,
189 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
190 will not be able to contact the DHCP server until the secure channel
191 has started up. Thus, start \fBsecchan\fR without configuring
192 the local port network device, and start the DHCP client afterward.
197 \fB--accept-vconn=\fIregex\fR
198 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
199 THE CONTROLLER\fR, above, for more information about controller
200 discovery), it validates the controller location obtained via DHCP
201 with a POSIX extended regular expression. Only controllers whose
202 names match the regular expression will be accepted.
204 The default regular expression is \fBssl:.*\fR (meaning that only SSL
205 controller connections will be accepted) when any of the SSL
206 configuration options \fB--private-key\fR, \fB--certificate\fR, or
207 \fB--ca-cert\fR is specified. The default is \fB.*\fR otherwise
208 (meaning that any controller will be accepted).
210 The \fIregex\fR is implicitly anchored at the beginning of the
211 controller location string, as if it begins with \fB^\fR.
213 When controller discovery is not performed, this option has no effect.
216 \fB--no-resolv-conf\fR
217 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
218 THE CONTROLLER\fR, above, for more information about controller
219 discovery), by default it overwrites the system's
220 \fB/etc/resolv.conf\fR with domain information and DNS servers
221 obtained via DHCP. If the location of the controller is specified
222 using a hostname, rather than an IP address, and the network's DNS
223 servers ever change, this behavior is essential. But because it also
224 interferes with any administrator or process that manages
225 \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR
226 will not modify \fB/etc/resolv.conf\fR.
228 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
229 that it receives specifies one or more DNS servers.
231 When controller discovery is not performed, this option has no effect.
234 \fB-F\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
235 The controller is, ordinarily, responsible for setting up all flows on
236 the OpenFlow switch. Thus, if the connection to the controller fails,
237 no new network connections can be set up. If the connection to the
238 controller stays down long enough, no packets can pass through the
241 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
242 take over responsibility for setting up flows in the local datapath
243 when no message has been received from the controller for three times
244 the inactivity probe interval (see below), or 45 seconds by default.
245 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
246 like an ordinary MAC-learning switch. \fBsecchan\fR will continue to
247 retry connection to the controller in the background and, when the
248 connection succeeds, it discontinues its fail-open behavior. The
249 secure channel enters the fail-open mode when
251 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
252 set up flows on its own when the controller connection fails.
255 \fB--inactivity-probe=\fIsecs\fR
256 When the secure channel is connected to the controller, the secure
257 channel waits for a message to be received from the controller for
258 \fIsecs\fR seconds before it sends a inactivity probe to the
259 controller. After sending the inactivity probe, if no response is
260 received for an additional \fIsecs\fR seconds, the secure channel
261 assumes that the connection has been broken and attempts to reconnect.
262 The default is 15 seconds, and the minimum value is 5 seconds.
264 When fail-open mode is configured, changing the inactivity probe
265 interval also changes the interval before entering fail-open mode (see
269 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
270 Sets \fIsecs\fR as the number of seconds that a flow set up by the
271 secure channel will remain in the switch's flow table without any
272 matching packets being seen. If \fBpermanent\fR is specified, which
273 is not recommended, flows set up by the secure channel will never
274 expire. The default is 15 seconds.
276 Most flows are set up by the OpenFlow controller, not by the secure
277 channel. This option affects only the following flows, which the
278 secure channel sets up itself:
282 When \fB--fail=open\fR is specified, flows set up when the secure
283 channel has not been able to contact the controller for the configured
287 When in-band control is in use, flows set up to bootstrap contacting
288 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
289 more information about in-band control).
293 As a result, when both \fB--fail=closed\fR and \fB--out-of-band\fR are
294 specified, this option has no effect.
297 \fB--max-backoff=\fIsecs\fR
298 Sets the maximum time between attempts to connect to the controller to
299 \fIsecs\fR, which must be at least 1. The actual interval between
300 connection attempts starts at 1 second and doubles on each failing
301 attempt until it reaches the maximum. The default maximum backoff
305 \fB-l\fR, \fB--listen=\fImethod\fR
306 Configures the switch to additionally listen for incoming OpenFlow
307 connections for switch management with \fBdpctl\fR. The \fImethod\fR
308 must be given as one of the passive OpenFlow connection methods listed
309 below. This option may be specified multiple times to listen to
310 multiple connection methods.
314 \fBpssl:\fR[\fIport\fR]
315 Listens for SSL connections on \fIport\fR (default: 6633). The
316 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
317 are mandatory when this form is used.
320 \fBptcp:\fR[\fIport\fR]
321 Listens for TCP connections on \fIport\fR (default: 6633).
325 Listens for connections on Unix domain server socket named \fIfile\fR.
329 \fB-m\fR, \fB--monitor=\fImethod\fR
330 Configures the switch to additionally listen for incoming OpenFlow
331 connections for switch monitoring with \fBdpctl\fR's \fBmonitor\fR
332 command. The \fImethod\fR must be given as one of the passive
333 OpenFlow connection methods listed above as acceptable for
336 When \fBdpctl monitor\fR makes a monitoring connection, \fBsecchan\fR
337 sends it a copy of every OpenFlow message sent to or received from the
338 kernel in the normal course of its operations. It does not send a
339 copy of any messages sent to or from the OpenFlow connection to the
340 controller. Most of these messages will be seen anyhow, however,
341 because \fBsecchan\fR mainly acts as a relay between the controller
342 and the kernel. \fBsecchan\fR also does not send a copy of any
343 messages sent to or from the OpenFlow connection to the controller.
344 Such messages will typically \fBnot\fR be seen, because \fBsecchan\fR
345 maintains a separate connection to the kernel for each management
348 Messages are copied to the monitoring connections on a best-effort
349 basis. In particular, if the socket buffer of the monitoring
350 connection fills up, some messages will be lost.
353 \fB--in-band\fR, \fB--out-of-band\fR
354 Configures \fBsecchan\fR to operate in in-band or out-of-band control
355 mode (see \fBCONTACTING THE CONTROLLER\fR above). When neither option
356 is given, the default is in-band control.
359 \fB--stp\fR, \fB--no-stp\fR
360 Enable or disable implementation of IEEE 802.1D Spanning Tree Protocol
361 at the switch. The default is \fB--no-stp\fR in this distribution,
362 because bugs in the STP implementation are still being worked out.
363 The default will change to \fB--stp\fR at some point in the future.
366 \fB--command-acl=\fR[\fB!\fR]\fIglob\fR[\fB,\fR[\fB!\fR]\fIglob\fR...]
367 Configures the commands that remote OpenFlow connections are allowed
368 to invoke using (e.g.) \fBdpctl execute\fR. The argument is a
369 comma-separated sequence of shell glob patterns. A glob pattern
370 specified without a leading \fB!\fR is a ``whitelist'' that specifies
371 a set of commands that are that may be invoked, whereas a pattern that
372 does begin with \fB!\fR is a ``blacklist'' that specifies commands
373 that may not be invoked. To be permitted, a command name must be
374 whitelisted and must not be blacklisted;
375 e.g. \fB--command-acl=up*,!upgrade\fR would allow any command whose name
376 begins with \fBup\fR except for the command named \fBupgrade\fR.
377 Command names that include characters other than upper- and lower-case
378 English letters, digits, and the underscore and hyphen characters are
379 unconditionally disallowed.
381 When the whitelist and blacklist permit a command name, \fBsecchan\fR
382 looks for a program with the same name as the command in the commands
383 directory (see below). Other directories are not searched.
386 \fB--command-dir=\fIdirectory\fR
387 Sets the directory searched for remote command execution to
388 \fBdirectory\fR. The default directory is
389 \fB@pkgdatadir@/commands\fR.
392 \fB--netflow=\fIhost\fB:\fIport\fR
393 When flows end on the switch, send NetFlow v5 messages to
394 \fIhost\fR on UDP \fIport\fR.
397 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
398 Specifies a PEM file containing the private key used as the switch's
399 identity for SSL connections to the controller.
402 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
403 Specifies a PEM file containing a certificate, signed by the
404 controller's certificate authority (CA), that certifies the switch's
405 private key to identify a trustworthy switch.
408 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
409 Specifies a PEM file containing the CA certificate used to verify that
410 the switch is connected to a trustworthy controller.
413 \fB--bootstrap-ca-cert=\fIcacert.pem\fR
414 When \fIcacert.pem\fR exists, this option has the same effect as
415 \fB-C\fR or \fB--ca-cert\fR. If it does not exist, then \fBsecchan\fR
416 will attempt to obtain the CA certificate from the controller on its
417 first SSL connection and save it to the named PEM file. If it is
418 successful, it will immediately drop the connection and reconnect, and
419 from then on all SSL connections must be authenticated by a
420 certificate signed by the CA certificate thus obtained.
422 \fBThis option exposes the SSL connection to a man-in-the-middle
423 attack obtaining the initial CA certificate\fR, but it may be useful
426 This option is only useful if the controller sends its CA certificate
427 as part of the SSL certificate chain. The SSL protocol does not
428 require the controller to send the CA certificate, but
429 \fBcontroller\fR(8) can be configured to do so with the
430 \fB--peer-ca-cert\fR option.
433 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
434 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
435 the PID of the running process. If \fIpidfile\fR is not specified, or
436 if it does not begin with \fB/\fR, then it is created in
440 \fB-f\fR, \fB--force\fR
441 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
442 specified pidfile already exists and is locked by a running process,
443 \fBsecchan\fR refuses to start. Specify \fB-f\fR or \fB--force\fR
444 to cause it to instead overwrite the pidfile.
446 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
450 \fB-D\fR, \fB--detach\fR
451 Causes \fBsecchan\fR to detach itself from the foreground session and
452 run as a background process.
455 .BR \-h ", " \-\^\-help
456 Prints a brief help message to the console.
461 .BR \-V ", " \-\^\-version
462 Prints version information to the console.
467 .BR ofp-discover (8),