1 .TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"
4 secchan \- secure channel connecting an OpenFlow datapath to a controller
8 [\fIoptions\fR] \fBnl:\fIdp_idx\fR [\fIremote\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 \fBnl:\fIdp_idx\fR argument specifies the local datapath
17 to relay. Within this argument, \fIdp_idx\fR is the number of a
18 datapath that has been created with
21 The optional \fIcontroller\fR argument specifies how to connect to
22 the OpenFlow controller. It takes one of the following forms:
25 \fBssl:\fIhost\fR[\fB:\fIport\fR]
26 The specified SSL \fIport\fR (default: 976) on the given remote
27 \fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
28 \fB--ca-cert\fR options are mandatory when this form is used.
31 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
32 The specified TCP \fIport\fR (default: 975) on the given remote
37 The Unix domain server socket named \fIfile\fR.
39 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
40 location of the controller automatically (see below).
42 .SH "CONTACTING THE CONTROLLER"
43 The OpenFlow switch must be able to contact the OpenFlow controller
44 over the network. It can do so in one of two ways:
47 In this configuration, OpenFlow traffic uses a network separate from
48 the data traffic that it controls, that is, the switch does not use
49 any of the network devices added to the datapath with \fBdpctl
50 addif\fR in its communication with the controller.
52 To use \fBsecchan\fR in a network with out-of-band control, the
53 control network must be configured for use by \fBsecchan\fR at the
54 time it is started. No additional setup is required. In particular,
55 the \fBof\fIn\fR device should not be up or configured with an IP
59 In this configuration, a single network is used for OpenFlow traffic
60 and other data traffic, that is, the switch contacts the controller
61 over one of the network devices added to the datapath with \fBdpctl
62 addif\fR. This configuration is often more convenient than
63 out-of-band control, because it is not necessary to maintain two
66 With in-band control, the location of the controller can be configured
67 manually or discovered automatically:
70 .IP "controller discovery"
71 To make \fBsecchan\fR discover the location of the controller
72 automatically, do not specify the location of the controller on the
73 \fBsecchan\fR command line.
75 In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
76 class identifier \fBOpenFlow\fR across the network devices added to
77 the datapath with \fBdpctl addif\fR. It will accept any valid DHCP
78 reply that has the same vendor class identifier and includes a
79 vendor-specific option with code 1 whose contents are a string
80 specifying the location of the controller in the same format used on
81 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
83 The DHCP reply may also, optionally, include a vendor-specific option
84 with code 2 whose contents are a string specifying the URI to the base
85 of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
86 This URI is used only for bootstrapping the OpenFlow PKI at initial
87 switch setup; \fBsecchan\fR does not use it at all.
89 The following ISC DHCP server configuration file assigns the IP
90 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
91 that follow the switch protocol and addresses 192.168.0.1 through
92 192.168.0.10 to all other DHCP clients:
94 default-lease-time 600;
98 option space openflow;
100 option openflow.controller-vconn code 1 = text;
102 option openflow.pki-uri code 2 = text;
106 match if option vendor-class-identifier = "OpenFlow";
108 vendor-option-space openflow;
110 option openflow.controller-vconn "tcp:192.168.0.10";
112 option openflow.pki-uri "http://192.168.0.10/openflow/pki";
114 option vendor-class-identifier "OpenFlow";
118 subnet 192.168.0.0 netmask 255.255.255.0 {
122 allow members of "OpenFlow";
124 range 192.168.0.20 192.168.0.30;
130 deny members of "OpenFlow";
132 range 192.168.0.1 192.168.0.10;
139 .IP "manual configuration"
140 Configuring in-band control manually requires
141 additional setup before starting \fBsecchan\fR. At a minimum, the
142 special OpenFlow network device \fBof\fIn\fR, where \fIn\fR is same as
143 the \fIdp_idx\fR specified on the \fBsecchan\fR command line, must be
152 Before \fBsecchan\fR starts, the \fBof\fIn\fR device cannot send or
153 receive any packets, so the next step depends on whether connectivity
154 is required to configure the device's IP address. If the switch has a
155 static IP address, you may configure its IP address now with a command
159 ifconfig of0 192.168.1.1
162 and then invoke \fBsecchan\fR.
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
166 will not be able to contact the DHCP server until the secure channel
167 has started up. Thus, start \fBsecchan\fR without configuring
168 \fBof\fIn\fR further, and start the DHCP client afterward.
173 \fB--accept-vconn=\fIregex\fR
174 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
175 THE CONTROLLER\fR, above, for more information about controller
176 discovery), it validates the controller location obtained via DHCP
177 with a POSIX extended regular expression. Only controllers whose
178 names match the regular expression will be accepted.
180 The default regular expression is \fBssl:.*\fR (meaning that only SSL
181 controller connections will be accepted) when any of the SSL
182 configuration options \fB--private-key\fR, \fB--certificate\fR, or
183 \fB--ca-cert\fR is specified. The default is \fB.*\fR otherwise
184 (meaning that any controller will be accepted).
186 The \fIregex\fR is implicitly anchored at the beginning of the
187 controller location string, as if it begins with \fB^\fR.
189 When controller discovery is not performed, this option has no effect.
192 \fB--no-resolv-conf\fR
193 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
194 THE CONTROLLER\fR, above, for more information about controller
195 discovery), by default it overwrites the system's
196 \fB/etc/resolv.conf\fR with domain information and DNS servers
197 obtained via DHCP. If the location of the controller is specified
198 using a hostname, rather than an IP address, and the network's DNS
199 servers ever change, this behavior is essential. But because it also
200 interferes with any administrator or process that manages
201 \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR
202 will not modify \fB/etc/resolv.conf\fR.
204 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
205 that it receives specifies one or more DNS servers.
207 When controller discovery is not performed, this option has no effect.
210 \fB-F\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
211 The controller is, ordinarily, responsible for setting up all flows on
212 the OpenFlow switch. Thus, if the connection to the controller fails,
213 no new network connections can be set up. If the connection to the
214 controller stays down long enough, no packets can pass through the
217 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
218 take over responsibility for setting up flows in the local datapath
219 when no message has been received from the controller for three times
220 the inactivity probe interval (see below), or 45 seconds by default.
221 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
222 like an ordinary MAC-learning switch. \fBsecchan\fR will continue to
223 retry connection to the controller in the background and, when the
224 connection succeeds, it discontinues its fail-open behavior. The
225 secure channel enters the fail-open mode when
227 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
228 set up flows on its own when the controller connection fails.
231 \fB--inactivity-probe=\fIsecs\fR
232 When the secure channel is connected to the controller, the secure
233 channel waits for a message to be received from the controller for
234 \fIsecs\fR seconds before it sends a inactivity probe to the
235 controller. After sending the inactivity probe, if no response is
236 received for an additional \fIsecs\fR seconds, the secure channel
237 assumes that the connection has been broken and attempts to reconnect.
238 The default is 15 seconds, and the minimum value is 5 seconds.
240 When fail-open mode is configured, changing the inactivity probe
241 interval also changes the interval before entering fail-open mode (see
245 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
246 Sets \fIsecs\fR as the number of seconds that a flow set up by the
247 secure channel will remain in the switch's flow table without any
248 matching packets being seen. If \fBpermanent\fR is specified, which
249 is not recommended, flows set up by the secure channel will never
250 expire. The default is 15 seconds.
252 Most flows are set up by the OpenFlow controller, not by the secure
253 channel. This option affects only the following flows, which the
254 secure channel sets up itself:
258 When \fB--fail=open\fR is specified, flows set up when the secure
259 channel has not been able to contact the controller for the configured
263 When in-band control is in use, flows set up to bootstrap contacting
264 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
265 more information about in-band control).
269 As a result, when both \fB--fail=open\fR and in-band control are not
270 in use, this option has no effect.
273 \fB--max-backoff=\fIsecs\fR
274 Sets the maximum time between attempts to connect to the controller to
275 \fIsecs\fR, which must be at least 1. The actual interval between
276 connection attempts starts at 1 second and doubles on each failing
277 attempt until it reaches the maximum. The default maximum backoff
281 \fB-l\fR, \fB--listen=\fImethod\fR
282 Configures the switch to additionally listen for incoming OpenFlow
283 connections for switch management with \fBdpctl\fR. The \fImethod\fR
284 must be given as one of the passive OpenFlow connection methods listed
285 below. This option may be specified multiple times to listen to
286 multiple connection methods.
290 \fBpssl:\fR[\fIport\fR]
291 Listens for SSL connections on \fIport\fR (default: 976). The
292 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
293 are mandatory when this form is used.
296 \fBptcp:\fR[\fIport\fR]
297 Listens for TCP connections on \fIport\fR (default: 975).
302 Listens for connections on Unix domain server socket named \fIfile\fR.
305 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
306 Specifies a PEM file containing the private key used as the switch's
307 identity for SSL connections to the controller.
310 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
311 Specifies a PEM file containing a certificate, signed by the
312 controller's certificate authority (CA), that certifies the switch's
313 private key to identify a trustworthy switch.
316 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
317 Specifies a PEM file containing the CA certificate used to verify that
318 the switch is connected to a trustworthy controller.
321 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
322 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
323 the PID of the running process. If \fIpidfile\fR is not specified, or
324 if it does not begin with \fB/\fR, then it is created in
328 \fB-f\fR, \fB--force\fR
329 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
330 specified pidfile already exists and is locked by a running process,
331 \fBsecchan\fR refuses to start. Specify \fB-f\fR or \fB--force\fR
332 to cause it to instead overwrite the pidfile.
334 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
338 \fB-D\fR, \fB--detach\fR
339 Causes \fBsecchan\fR to detach itself from the foreground session and
340 run as a background process.
343 .BR \-h ", " \-\^\-help
344 Prints a brief help message to the console.
347 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
348 Sets the logging level for \fImodule\fR in \fIfacility\fR to
349 \fIlevel\fR. The \fImodule\fR may be any valid module name (as
350 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
351 special name \fBANY\fR to set the logging levels for all modules. The
352 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
353 for logging to the system log or to the console, respectively, or
354 \fBANY\fR to set the logging levels for both facilities. If it is
355 omitted, \fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must
356 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
357 the minimum severity of a message for it to be logged. If it is
358 omitted, \fIlevel\fR defaults to \fBdbg\fR.
361 \fB-v\fR, \fB--verbose\fR
362 Sets the maximum logging verbosity level, equivalent to
363 \fB--verbose=ANY:ANY:dbg\fR.
366 .BR \-V ", " \-\^\-version
367 Prints version information to the console.
372 .BR ofp-discover (8),