secchan/secchan.8.in

   1 .TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 secchan \- secure channel connecting an OpenFlow datapath to a controller
   5
   6 .SH SYNOPSIS
   7 .B secchan
   8 [\fIoptions\fR] \fBnl:\fIdp_idx\fR [\fIremote\fR]
   9
  10 .SH DESCRIPTION
  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.
  15
  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
  19 .BR dpctl (8).
  20
  21 The optional \fIcontroller\fR argument specifies how to connect to
  22 the OpenFlow controller.  It takes one of the following forms:
  23
  24 .TP
  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.
  29
  30 .TP
  31 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
  32 The specified TCP \fIport\fR (default: 975) on the given remote
  33 \fIhost\fR.
  34
  35 .TP
  36 \fBunix:\fIfile\fR
  37 The Unix domain server socket named \fIfile\fR.
  38
  39 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
  40 location of the controller automatically (see below).
  41
  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:
  45
  46 .IP out-of-band
  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.
  51
  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
  56 address (see below).
  57
  58 .IP in-band
  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
  64 independent networks.
  65
  66 With in-band control, the location of the controller can be configured
  67 manually or discovered automatically:
  68
  69 .RS
  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.
  74
  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).
  82
  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.
  88
  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:
  93
  94 default-lease-time 600;
  95 .br
  96 max-lease-time 7200;
  97 .br
  98 option space openflow;
  99 .br
 100 option openflow.controller-vconn code 1 = text;
 101 .br
 102 option openflow.pki-uri code 2 = text;
 103 .br
 104 class "OpenFlow" {
 105 .br
 106   match if option vendor-class-identifier = "OpenFlow";
 107 .br
 108   vendor-option-space openflow;
 109 .br
 110   option openflow.controller-vconn "tcp:192.168.0.10";
 111 .br
 112   option openflow.pki-uri "http://192.168.0.10/openflow/pki";
 113 .br
 114   option vendor-class-identifier "OpenFlow";
 115 .br
 116 }
 117 .br
 118 subnet 192.168.0.0 netmask 255.255.255.0 {
 119 .br
 120     pool {
 121 .br
 122         allow members of "OpenFlow";
 123 .br
 124         range 192.168.0.20 192.168.0.30;
 125 .br
 126     }
 127 .br
 128     pool {
 129 .br
 130         deny members of "OpenFlow";
 131 .br
 132         range 192.168.0.1 192.168.0.10;
 133 .br
 134     }
 135 .br
 136 }
 137 .br
 138
 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
 144 brought up using
 145 .BR ifconfig (8),
 146 e.g.:
 147 .RS
 148 .IP
 149 ifconfig of0 up
 150 .RE
 151 .IP
 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
 156 such as:
 157 .RS
 158 .IP
 159 ifconfig of0 192.168.1.1
 160 .RE
 161 .IP
 162 and then invoke \fBsecchan\fR.
 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
 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.
 169 .RE
 170
 171 .SH OPTIONS
 172 .TP
 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.
 179
 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).
 185
 186 The \fIregex\fR is implicitly anchored at the beginning of the
 187 controller location string, as if it begins with \fB^\fR.
 188
 189 When controller discovery is not performed, this option has no effect.
 190
 191 .TP
 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.
 203
 204 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
 205 that it receives specifies one or more DNS servers.
 206
 207 When controller discovery is not performed, this option has no effect.
 208
 209 .TP
 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
 215 switch at all.
 216
 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
 226
 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.
 229
 230 .TP
 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.
 239
 240 When fail-open mode is configured, changing the inactivity probe
 241 interval also changes the interval before entering fail-open mode (see
 242 above).
 243
 244 .TP
 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.
 251
 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:
 255
 256 .RS
 257 .IP \(bu
 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
 260 fail-open delay.
 261
 262 .IP \(bu
 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).
 266 .RE
 267
 268 .IP
 269 As a result, when both \fB--fail=open\fR and in-band control are not
 270 in use, this option has no effect.
 271
 272 .TP
 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
 278 time is 15 seconds.
 279
 280 .TP
 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.
 287
 288 .RS
 289 .TP
 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.
 294
 295 .TP
 296 \fBptcp:\fR[\fIport\fR]
 297 Listens for TCP connections on \fIport\fR (default: 975).
 298
 299 .TP
 300 \fBpunix:\fIfile\fR
 301 Listens for connections on Unix domain server socket named \fIfile\fR.
 302 .RE
 303
 304 .TP
 305 \fB-m\fR, \fB--monitor=\fImethod\fR
 306 Configures the switch to additionally listen for incoming OpenFlow
 307 connections for switch monitoring with \fBdpctl\fR's \fBmonitor\fR
 308 command.  The \fImethod\fR must be given as one of the passive
 309 OpenFlow connection methods listed above as acceptable for
 310 \fB--listen\fR.
 311
 312 When \fBdpctl monitor\fR makes a monitoring connection, \fBsecchan\fR
 313 sends it a copy of every OpenFlow message sent to or received from the
 314 kernel in the normal course of its operations.  It does not send a
 315 copy of any messages sent to or from the OpenFlow connection to the
 316 controller.  Most of these messages will be seen anyhow, however,
 317 because \fBsecchan\fR mainly acts as a relay between the controller
 318 and the kernel.  \fBsecchan\fR also does not send a copy of any
 319 messages sent to or from the OpenFlow connection to the controller.
 320 Such messages will typically \fBnot\fR be seen, because \fBsecchan\fR
 321 maintains a separate connection to the kernel for each management
 322 connection.
 323
 324 Messages are copied to the monitoring connections on a best-effort
 325 basis.  In particular, if the socket buffer of the monitoring
 326 connection fills up, some messages will be lost.
 327
 328 .TP
 329 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 330 Specifies a PEM file containing the private key used as the switch's
 331 identity for SSL connections to the controller.
 332
 333 .TP
 334 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 335 Specifies a PEM file containing a certificate, signed by the
 336 controller's certificate authority (CA), that certifies the switch's
 337 private key to identify a trustworthy switch.
 338
 339 .TP
 340 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 341 Specifies a PEM file containing the CA certificate used to verify that
 342 the switch is connected to a trustworthy controller.
 343
 344 .TP
 345 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 346 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 347 the PID of the running process.  If \fIpidfile\fR is not specified, or
 348 if it does not begin with \fB/\fR, then it is created in
 349 \fB@rundir@\fR.
 350
 351 .TP
 352 \fB-f\fR, \fB--force\fR
 353 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
 354 specified pidfile already exists and is locked by a running process,
 355 \fBsecchan\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
 356 to cause it to instead overwrite the pidfile.
 357
 358 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 359 effect.
 360
 361 .TP
 362 \fB-D\fR, \fB--detach\fR
 363 Causes \fBsecchan\fR to detach itself from the foreground session and
 364 run as a background process.
 365
 366 .TP
 367 .BR \-h ", " \-\^\-help
 368 Prints a brief help message to the console.
 369
 370 .TP
 371 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 372 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 373 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 374 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 375 special name \fBANY\fR to set the logging levels for all modules.  The
 376 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 377 for logging to the system log or to the console, respectively, or
 378 \fBANY\fR to set the logging levels for both facilities.  If it is
 379 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 380 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 381 the minimum severity of a message for it to be logged.  If it is
 382 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 383
 384 .TP
 385 \fB-v\fR, \fB--verbose\fR
 386 Sets the maximum logging verbosity level, equivalent to
 387 \fB--verbose=ANY:ANY:dbg\fR.
 388
 389 .TP
 390 .BR \-V ", " \-\^\-version
 391 Prints version information to the console.
 392
 393 .SH "SEE ALSO"
 394
 395 .BR dpctl (8),
 396 .BR ofp-discover (8),
 397 .BR controller (8),
 398 .BR ofp-pki (8),
 399 .BR vlogconf (8),
 400 .BR switch (8)