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
35 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
36 location of the controller automatically (see below).
38 .SH "CONTACTING THE CONTROLLER"
39 The OpenFlow switch must be able to contact the OpenFlow controller
40 over the network. It can do so in one of two ways:
43 In this configuration, OpenFlow traffic uses a network separate from
44 the data traffic that it controls, that is, the switch does not use
45 any of the network devices added to the datapath with \fBdpctl
46 addif\fR in its communication with the controller.
48 To use \fBsecchan\fR in a network with out-of-band control, the
49 control network must be configured for use by \fBsecchan\fR at the
50 time it is started. No additional setup is required. In particular,
51 the \fBof\fIn\fR device should not be up or configured with an IP
55 In this configuration, a single network is used for OpenFlow traffic
56 and other data traffic, that is, the switch contacts the controller
57 over one of the network devices added to the datapath with \fBdpctl
58 addif\fR. This configuration is often more convenient than
59 out-of-band control, because it is not necessary to maintain two
62 With in-band control, the location of the controller can be configured
63 manually or discovered automatically:
66 .IP "controller discovery"
67 To make \fBsecchan\fR discover the location of the controller
68 automatically, do not specify the location of the controller on the
69 \fBsecchan\fR command line.
71 In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
72 class identifier \fBOpenFlow\fR across the network devices added to
73 the datapath with \fBdpctl addif\fR. It will accept any valid DHCP
74 reply that has the same vendor class identifier and includes a
75 vendor-specific option with code 1 whose contents are a string
76 specifying the location of the controller in the same format used on
77 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
79 The DHCP reply may also, optionally, include a vendor-specific option
80 with code 2 whose contents are a string specifying the URI to the base
81 of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
82 This URI is used only for bootstrapping the OpenFlow PKI at initial
83 switch setup; \fBsecchan\fR does not use it at all.
85 The following ISC DHCP server configuration file assigns the IP
86 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
87 that follow the switch protocol and addresses 192.168.0.1 through
88 192.168.0.10 to all other DHCP clients:
90 default-lease-time 600;
94 option space openflow;
96 option openflow.controller-vconn code 1 = text;
98 option openflow.pki-uri code 2 = text;
102 match if option vendor-class-identifier = "OpenFlow";
104 vendor-option-space openflow;
106 option openflow.controller-vconn "tcp:192.168.0.10";
108 option openflow.pki-uri "http://192.168.0.10/openflow/pki";
110 option vendor-class-identifier "OpenFlow";
114 subnet 192.168.0.0 netmask 255.255.255.0 {
118 allow members of "OpenFlow";
120 range 192.168.0.20 192.168.0.30;
126 deny members of "OpenFlow";
128 range 192.168.0.1 192.168.0.10;
135 .IP "manual configuration"
136 Configuring in-band control manually requires
137 additional setup before starting \fBsecchan\fR. At a minimum, the
138 special OpenFlow network device \fBof\fIn\fR, where \fIn\fR is same as
139 the \fIdp_idx\fR specified on the \fBsecchan\fR command line, must be
148 Before \fBsecchan\fR starts, the \fBof\fIn\fR device cannot send or
149 receive any packets, so the next step depends on whether connectivity
150 is required to configure the device's IP address. If the switch has a
151 static IP address, you may configure its IP address now with a command
155 ifconfig of0 192.168.1.1
158 and then invoke \fBsecchan\fR.
160 On the other hand, if the switch does not have a static IP address,
161 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
162 will not be able to contact the DHCP server until the secure channel
163 has started up. Thus, start \fBsecchan\fR without configuring
164 \fBof\fIn\fR further, and start the DHCP client afterward.
169 \fB--accept-vconn=\fIregex\fR
170 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
171 THE CONTROLLER\fR, above, for more information about controller
172 discovery), it validates the controller location obtained via DHCP
173 with a POSIX extended regular expression. Only controllers whose
174 names match the regular expression will be accepted.
176 The default regular expression is \fBssl:.*\fR (meaning that only SSL
177 controller connections will be accepted) when any of the SSL
178 configuration options \fB--private-key\fR, \fB--certificate\fR, or
179 \fB--ca-cert\fR is specified. The default is \fB.*\fR otherwise
180 (meaning that any controller will be accepted).
182 The \fIregex\fR is implicitly anchored at the beginning of the
183 controller location string, as if it begins with \fB^\fR.
185 When controller discovery is not performed, this option has no effect.
188 \fB--no-resolv-conf\fR
189 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
190 THE CONTROLLER\fR, above, for more information about controller
191 discovery), by default it overwrites the system's
192 \fB/etc/resolv.conf\fR with domain information and DNS servers
193 obtained via DHCP. If the location of the controller is specified
194 using a hostname, rather than an IP address, and the network's DNS
195 servers ever change, this behavior is essential. But because it also
196 interferes with any administrator or process that manages
197 \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR
198 will not modify \fB/etc/resolv.conf\fR.
200 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
201 that it receives specifies one or more DNS servers.
203 When controller discovery is not performed, this option has no effect.
206 \fB-f\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
207 The controller is, ordinarily, responsible for setting up all flows on
208 the OpenFlow switch. Thus, if the connection to the controller fails,
209 no new network connections can be set up. If the connection to the
210 controller stays down long enough, no packets can pass through the
213 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
214 take over responsibility for setting up flows in the local datapath
215 when no message has been received from the controller for three times
216 the inactivity probe interval (see below), or 45 seconds by default.
217 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
218 like an ordinary MAC-learning switch. \fBsecchan\fR will continue to
219 retry connection to the controller in the background and, when the
220 connection succeeds, it discontinues its fail-open behavior. The
221 secure channel enters the fail-open mode when
223 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
224 set up flows on its own when the controller connection fails.
227 \fB--inactivity-probe=\fIsecs\fR
228 When the secure channel is connected to the controller, the secure
229 channel waits for a message to be received from the controller for
230 \fIsecs\fR seconds before it sends a inactivity probe to the
231 controller. After sending the inactivity probe, if no response is
232 received for an additional \fIsecs\fR seconds, the secure channel
233 assumes that the connection has been broken and attempts to reconnect.
234 The default is 15 seconds, and the minimum value is 5 seconds.
236 When fail-open mode is configured, changing the inactivity probe
237 interval also changes the interval before entering fail-open mode (see
241 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
242 Sets \fIsecs\fR as the number of seconds that a flow set up by the
243 secure channel will remain in the switch's flow table without any
244 matching packets being seen. If \fBpermanent\fR is specified, which
245 is not recommended, flows set up by the secure channel will never
246 expire. The default is 15 seconds.
248 Most flows are set up by the OpenFlow controller, not by the secure
249 channel. This option affects only the following flows, which the
250 secure channel sets up itself:
254 When \fB--fail=open\fR is specified, flows set up when the secure
255 channel has not been able to contact the controller for the configured
259 When in-band control is in use, flows set up to bootstrap contacting
260 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
261 more information about in-band control).
265 As a result, when both \fB--fail=open\fR and in-band control are not
266 in use, this option has no effect.
269 \fB--max-backoff=\fIsecs\fR
270 Sets the maximum time between attempts to connect to the controller to
271 \fIsecs\fR, which must be at least 1. The actual interval between
272 connection attempts starts at 1 second and doubles on each failing
273 attempt until it reaches the maximum. The default maximum backoff
277 \fB-l\fR, \fB--listen=\fImethod\fR
278 Configures the switch to additionally listen for incoming OpenFlow
279 connections for switch management with \fBdpctl\fR. The \fImethod\fR
280 must be given as one of the following passive OpenFlow connection
285 \fBpssl:\fR[\fIport\fR]
286 Listens for SSL connections on \fIport\fR (default: 976). The
287 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
288 are mandatory when this form is used.
291 \fBptcp:\fR[\fIport\fR]
292 Listens for TCP connections on \fIport\fR (default: 975).
296 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
297 Specifies a PEM file containing the private key used as the switch's
298 identity for SSL connections to the controller.
301 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
302 Specifies a PEM file containing a certificate, signed by the
303 controller's certificate authority (CA), that certifies the switch's
304 private key to identify a trustworthy switch.
307 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
308 Specifies a PEM file containing the CA certificate used to verify that
309 the switch is connected to a trustworthy controller.
312 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
313 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
314 the PID of the running process. If \fIpidfile\fR is not specified, or
315 if it does not begin with \fB/\fR, then it is created in
319 \fB-D\fR, \fB--detach\fR
320 Causes \fBsecchan\fR to detach itself from the foreground session and
321 run as a background process.
324 .BR \-h ", " \-\^\-help
325 Prints a brief help message to the console.
328 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
329 Sets the logging level for \fImodule\fR in \fIfacility\fR to
330 \fIlevel\fR. The \fImodule\fR may be any valid module name (as
331 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
332 special name \fBANY\fR to set the logging levels for all modules. The
333 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
334 for logging to the system log or to the console, respectively, or
335 \fBANY\fR to set the logging levels for both facilities. If it is
336 omitted, \fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must
337 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
338 the minimum severity of a message for it to be logged. If it is
339 omitted, \fIlevel\fR defaults to \fBdbg\fR.
342 \fB-v\fR, \fB--verbose\fR
343 Sets the maximum logging verbosity level, equivalent to
344 \fB--verbose=ANY:ANY:dbg\fR.
347 .BR \-V ", " \-\^\-version
348 Prints version information to the console.
353 .BR ofp-discover (8),