secchan/secchan.8.in

   1 .TH secchan 8 "October 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] \fIdatapath\fR [\fIcontroller\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 \fIdatapath\fR argument argument specifies the local datapath
  17 to relay.  It takes one of the following forms:
  18
  19 .TP
  20 \fBnl:\fIdp_idx\fR
  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
  23 \fBdpctl\fR(8).
  24
  25 .TP
  26 \fBunix:\fIfile\fR
  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.
  30
  31 The optional \fIcontroller\fR argument specifies how to connect to
  32 the OpenFlow controller.  It takes one of the following forms:
  33
  34 .TP
  35 \fBssl:\fIhost\fR[\fB:\fIport\fR]
  36 The specified SSL \fIport\fR (default: 6633) on the given remote
  37 \fIhost\fR.  The \fB--private-key\fR, \fB--certificate\fR, and
  38 \fB--ca-cert\fR options are mandatory when this form is used.
  39
  40 .TP
  41 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
  42 The specified TCP \fIport\fR (default: 6633) on the given remote
  43 \fIhost\fR.
  44
  45 .TP
  46 \fBunix:\fIfile\fR
  47 The Unix domain server socket named \fIfile\fR.
  48
  49 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
  50 location of the controller automatically (see below).
  51
  52 .SH "CONTACTING THE CONTROLLER"
  53 The OpenFlow switch must be able to contact the OpenFlow controller
  54 over the network.  It can do so in one of two ways:
  55
  56 .IP out-of-band
  57 In this configuration, OpenFlow traffic uses a network separate from
  58 the data traffic that it controls, that is, the switch does not use
  59 any of the network devices added to the datapath with \fBdpctl
  60 addif\fR in its communication with the controller.
  61
  62 To use \fBsecchan\fR in a network with out-of-band control, specify
  63 \fB--out-of-band\fR on the \fBsecchan\fR command line.  The control
  64 network must be configured separately, before or after \fBsecchan\fR
  65 is started.
  66
  67 .IP in-band
  68 In this configuration, a single network is used for OpenFlow traffic
  69 and other data traffic, that is, the switch contacts the controller
  70 over one of the network devices added to the datapath with \fBdpctl
  71 addif\fR.  This configuration is often more convenient than
  72 out-of-band control, because it is not necessary to maintain two
  73 independent networks.
  74
  75 In-band control is the default for \fBsecchan\fR, so no special
  76 command-line option is required.
  77
  78 With in-band control, the location of the controller can be configured
  79 manually or discovered automatically:
  80
  81 .RS
  82 .IP "controller discovery"
  83 To make \fBsecchan\fR discover the location of the controller
  84 automatically, do not specify the location of the controller on the
  85 \fBsecchan\fR command line.
  86
  87 In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
  88 class identifier \fBOpenFlow\fR across the network devices added to
  89 the datapath with \fBdpctl addif\fR.  It will accept any valid DHCP
  90 reply that has the same vendor class identifier and includes a
  91 vendor-specific option with code 1 whose contents are a string
  92 specifying the location of the controller in the same format used on
  93 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
  94
  95 The DHCP reply may also, optionally, include a vendor-specific option
  96 with code 2 whose contents are a string specifying the URI to the base
  97 of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
  98 This URI is used only for bootstrapping the OpenFlow PKI at initial
  99 switch setup; \fBsecchan\fR does not use it at all.
 100
 101 The following ISC DHCP server configuration file assigns the IP
 102 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
 103 that follow the switch protocol and addresses 192.168.0.1 through
 104 192.168.0.10 to all other DHCP clients:
 105
 106 default-lease-time 600;
 107 .br
 108 max-lease-time 7200;
 109 .br
 110 option space openflow;
 111 .br
 112 option openflow.controller-vconn code 1 = text;
 113 .br
 114 option openflow.pki-uri code 2 = text;
 115 .br
 116 class "OpenFlow" {
 117 .br
 118   match if option vendor-class-identifier = "OpenFlow";
 119 .br
 120   vendor-option-space openflow;
 121 .br
 122   option openflow.controller-vconn "tcp:192.168.0.10";
 123 .br
 124   option openflow.pki-uri "http://192.168.0.10/openflow/pki";
 125 .br
 126   option vendor-class-identifier "OpenFlow";
 127 .br
 128 }
 129 .br
 130 subnet 192.168.0.0 netmask 255.255.255.0 {
 131 .br
 132     pool {
 133 .br
 134         allow members of "OpenFlow";
 135 .br
 136         range 192.168.0.20 192.168.0.30;
 137 .br
 138     }
 139 .br
 140     pool {
 141 .br
 142         deny members of "OpenFlow";
 143 .br
 144         range 192.168.0.1 192.168.0.10;
 145 .br
 146     }
 147 .br
 148 }
 149 .br
 150
 151 .IP "manual configuration"
 152 To configure in-band control manually, specify the location of the
 153 controller on the \fBsecchan\fR command line as the \fIcontroller\fR
 154 argument.  You must also configure the network device for the OpenFlow
 155 ``local port'' to allow \fBsecchan\fR to connect to that controller.
 156 The OpenFlow local port is a virtual network port that \fBsecchan\fR
 157 bridges to the physical switch ports.  Its network device name depends
 158 on the \fIdatapath\fR specified on the \fBsecchan\fR command line:
 159
 160 .RS
 161 .TP
 162 \fBnl:\fIdp_idx\fR
 163 The local port network device for \fBnl:\fIdp_idx\fR is always named
 164 \fBof\fIdp_idx\fR, i.e. the device for \fBnl:0\fR is \fBof0\fR.
 165
 166 .TP
 167 \fBunix:\fIfile\fR
 168 The local port network device name may be specified on the
 169 \fBudatapath\fR command line, using the \fB--local-port\fR option.  It
 170 is often \fBtap0\fR.
 171 .RE
 172
 173 .IP
 174 Before \fBsecchan\fR starts, the local port network device is not
 175 bridged to any physical network, so the next step depends on whether
 176 connectivity is required to configure the device's IP address.  If the
 177 switch has a static IP address, you may configure its IP address now
 178 with a command such as:
 179 .RS
 180 .IP
 181 ifconfig of0 192.168.1.1
 182 .RE
 183 .IP
 184 and then invoke \fBsecchan\fR.
 185
 186 On the other hand, if the switch does not have a static IP address,
 187 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
 188 will not be able to contact the DHCP server until the secure channel
 189 has started up.  Thus, start \fBsecchan\fR without configuring
 190 the local port network device, and start the DHCP client afterward.
 191 .RE
 192
 193 .SH OPTIONS
 194 .TP
 195 \fB--accept-vconn=\fIregex\fR
 196 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
 197 THE CONTROLLER\fR, above, for more information about controller
 198 discovery), it validates the controller location obtained via DHCP
 199 with a POSIX extended regular expression.  Only controllers whose
 200 names match the regular expression will be accepted.
 201
 202 The default regular expression is \fBssl:.*\fR (meaning that only SSL
 203 controller connections will be accepted) when any of the SSL
 204 configuration options \fB--private-key\fR, \fB--certificate\fR, or
 205 \fB--ca-cert\fR is specified.  The default is \fB.*\fR otherwise
 206 (meaning that any controller will be accepted).
 207
 208 The \fIregex\fR is implicitly anchored at the beginning of the
 209 controller location string, as if it begins with \fB^\fR.
 210
 211 When controller discovery is not performed, this option has no effect.
 212
 213 .TP
 214 \fB--no-resolv-conf\fR
 215 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
 216 THE CONTROLLER\fR, above, for more information about controller
 217 discovery), by default it overwrites the system's
 218 \fB/etc/resolv.conf\fR with domain information and DNS servers
 219 obtained via DHCP.  If the location of the controller is specified
 220 using a hostname, rather than an IP address, and the network's DNS
 221 servers ever change, this behavior is essential.  But because it also
 222 interferes with any administrator or process that manages
 223 \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR
 224 will not modify \fB/etc/resolv.conf\fR.
 225
 226 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
 227 that it receives specifies one or more DNS servers.
 228
 229 When controller discovery is not performed, this option has no effect.
 230
 231 .TP
 232 \fB-F\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
 233 The controller is, ordinarily, responsible for setting up all flows on
 234 the OpenFlow switch.  Thus, if the connection to the controller fails,
 235 no new network connections can be set up.  If the connection to the
 236 controller stays down long enough, no packets can pass through the
 237 switch at all.
 238
 239 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
 240 take over responsibility for setting up flows in the local datapath
 241 when no message has been received from the controller for three times
 242 the inactivity probe interval (see below), or 45 seconds by default.
 243 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
 244 like an ordinary MAC-learning switch.  \fBsecchan\fR will continue to
 245 retry connection to the controller in the background and, when the
 246 connection succeeds, it discontinues its fail-open behavior.  The
 247 secure channel enters the fail-open mode when
 248
 249 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
 250 set up flows on its own when the controller connection fails.
 251
 252 .TP
 253 \fB--inactivity-probe=\fIsecs\fR
 254 When the secure channel is connected to the controller, the secure
 255 channel waits for a message to be received from the controller for
 256 \fIsecs\fR seconds before it sends a inactivity probe to the
 257 controller.  After sending the inactivity probe, if no response is
 258 received for an additional \fIsecs\fR seconds, the secure channel
 259 assumes that the connection has been broken and attempts to reconnect.
 260 The default is 15 seconds, and the minimum value is 5 seconds.
 261
 262 When fail-open mode is configured, changing the inactivity probe
 263 interval also changes the interval before entering fail-open mode (see
 264 above).
 265
 266 .TP
 267 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 268 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 269 secure channel will remain in the switch's flow table without any
 270 matching packets being seen.  If \fBpermanent\fR is specified, which
 271 is not recommended, flows set up by the secure channel will never
 272 expire.  The default is 15 seconds.
 273
 274 Most flows are set up by the OpenFlow controller, not by the secure
 275 channel.  This option affects only the following flows, which the
 276 secure channel sets up itself:
 277
 278 .RS
 279 .IP \(bu
 280 When \fB--fail=open\fR is specified, flows set up when the secure
 281 channel has not been able to contact the controller for the configured
 282 fail-open delay.
 283
 284 .IP \(bu
 285 When in-band control is in use, flows set up to bootstrap contacting
 286 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
 287 more information about in-band control).
 288 .RE
 289
 290 .IP
 291 As a result, when both \fB--fail=open\fR and in-band control are not
 292 in use, this option has no effect.
 293
 294 .TP
 295 \fB--max-backoff=\fIsecs\fR
 296 Sets the maximum time between attempts to connect to the controller to
 297 \fIsecs\fR, which must be at least 1.  The actual interval between
 298 connection attempts starts at 1 second and doubles on each failing
 299 attempt until it reaches the maximum.  The default maximum backoff
 300 time is 15 seconds.
 301
 302 .TP
 303 \fB-l\fR, \fB--listen=\fImethod\fR
 304 Configures the switch to additionally listen for incoming OpenFlow
 305 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 306 must be given as one of the passive OpenFlow connection methods listed
 307 below.  This option may be specified multiple times to listen to
 308 multiple connection methods.
 309
 310 .RS
 311 .TP
 312 \fBpssl:\fR[\fIport\fR]
 313 Listens for SSL connections on \fIport\fR (default: 6633).  The
 314 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 315 are mandatory when this form is used.
 316
 317 .TP
 318 \fBptcp:\fR[\fIport\fR]
 319 Listens for TCP connections on \fIport\fR (default: 6633).
 320
 321 .TP
 322 \fBpunix:\fIfile\fR
 323 Listens for connections on Unix domain server socket named \fIfile\fR.
 324 .RE
 325
 326 .TP
 327 \fB-m\fR, \fB--monitor=\fImethod\fR
 328 Configures the switch to additionally listen for incoming OpenFlow
 329 connections for switch monitoring with \fBdpctl\fR's \fBmonitor\fR
 330 command.  The \fImethod\fR must be given as one of the passive
 331 OpenFlow connection methods listed above as acceptable for
 332 \fB--listen\fR.
 333
 334 When \fBdpctl monitor\fR makes a monitoring connection, \fBsecchan\fR
 335 sends it a copy of every OpenFlow message sent to or received from the
 336 kernel in the normal course of its operations.  It does not send a
 337 copy of any messages sent to or from the OpenFlow connection to the
 338 controller.  Most of these messages will be seen anyhow, however,
 339 because \fBsecchan\fR mainly acts as a relay between the controller
 340 and the kernel.  \fBsecchan\fR also does not send a copy of any
 341 messages sent to or from the OpenFlow connection to the controller.
 342 Such messages will typically \fBnot\fR be seen, because \fBsecchan\fR
 343 maintains a separate connection to the kernel for each management
 344 connection.
 345
 346 Messages are copied to the monitoring connections on a best-effort
 347 basis.  In particular, if the socket buffer of the monitoring
 348 connection fills up, some messages will be lost.
 349
 350 .TP
 351 \fB--in-band\fR, \fB--out-of-band\fR
 352 Configures \fBsecchan\fR to operate in in-band or out-of-band control
 353 mode (see \fBCONTACTING THE CONTROLLER\fR above).  When neither option
 354 is given, the default is in-band control.
 355
 356 .TP
 357 \fB--stp\fR, \fB--no-stp\fR
 358 Enable or disable implementation of IEEE 802.1D Spanning Tree Protocol
 359 at the switch.  The default is \fB--no-stp\fR in this distribution,
 360 because bugs in the STP implementation are still being worked out.
 361 The default will change to \fB--stp\fR at some point in the future.
 362
 363 .TP
 364 \fB--command-acl=\fR[\fB!\fR]\fIglob\fR[\fB,\fR[\fB!\fR]\fIglob\fR...]
 365 Configures the commands that remote OpenFlow connections are allowed
 366 to invoke using (e.g.) \fBdpctl execute\fR.  The argument is a
 367 comma-separated sequence of shell glob patterns.  A glob pattern
 368 specified without a leading \fB!\fR is a ``whitelist'' that specifies
 369 a set of commands that are that may be invoked, whereas a pattern that
 370 does begin with \fB!\fR is a ``blacklist'' that specifies commands
 371 that may not be invoked.  To be permitted, a command name must be
 372 whitelisted and must not be blacklisted;
 373 e.g. \fB--command-acl=up*,!upgrade\fR would allow any command whose name
 374 begins with \fBup\fR except for the command named \fBupgrade\fR.
 375 Command names that include characters other than upper- and lower-case
 376 English letters, digits, and the underscore and hyphen characters are
 377 unconditionally disallowed.
 378
 379 When the whitelist and blacklist permit a command name, \fBsecchan\fR
 380 looks for a program with the same name as the command in the commands
 381 directory (see below).  Other directories are not searched.
 382
 383 .TP
 384 \fB--command-dir=\fIdirectory\fR
 385 Sets the directory searched for remote command execution to
 386 \fBdirectory\fR.  The default directory is
 387 \fB@pkgdatadir@/commands\fR.
 388
 389 .TP
 390 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 391 Specifies a PEM file containing the private key used as the switch's
 392 identity for SSL connections to the controller.
 393
 394 .TP
 395 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 396 Specifies a PEM file containing a certificate, signed by the
 397 controller's certificate authority (CA), that certifies the switch's
 398 private key to identify a trustworthy switch.
 399
 400 .TP
 401 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 402 Specifies a PEM file containing the CA certificate used to verify that
 403 the switch is connected to a trustworthy controller.
 404
 405 .TP
 406 \fB--bootstrap-ca-cert=\fIcacert.pem\fR
 407 When \fIcacert.pem\fR exists, this option has the same effect as
 408 \fB-C\fR or \fB--ca-cert\fR.  If it does not exist, then \fBsecchan\fR
 409 will attempt to obtain the CA certificate from the controller on its
 410 first SSL connection and save it to the named PEM file.  If it is
 411 successful, it will immediately drop the connection and reconnect, and
 412 from then on all SSL connections must be authenticated by a
 413 certificate signed by the CA certificate thus obtained.
 414
 415 \fBThis option exposes the SSL connection to a man-in-the-middle
 416 attack obtaining the initial CA certificate\fR, but it may be useful
 417 for bootstrapping.
 418
 419 This option is only useful if the controller sends its CA certificate
 420 as part of the SSL certificate chain.  The SSL protocol does not
 421 require the controller to send the CA certificate, but
 422 \fBcontroller\fR(8) can be configured to do so with the
 423 \fB--peer-ca-cert\fR option.
 424
 425 .TP
 426 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 427 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 428 the PID of the running process.  If \fIpidfile\fR is not specified, or
 429 if it does not begin with \fB/\fR, then it is created in
 430 \fB@RUNDIR@\fR.
 431
 432 .TP
 433 \fB-f\fR, \fB--force\fR
 434 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
 435 specified pidfile already exists and is locked by a running process,
 436 \fBsecchan\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
 437 to cause it to instead overwrite the pidfile.
 438
 439 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 440 effect.
 441
 442 .TP
 443 \fB-D\fR, \fB--detach\fR
 444 Causes \fBsecchan\fR to detach itself from the foreground session and
 445 run as a background process.
 446
 447 .TP
 448 .BR \-h ", " \-\^\-help
 449 Prints a brief help message to the console.
 450
 451 @VLOG_OPTIONS@
 452
 453 .TP
 454 .BR \-V ", " \-\^\-version
 455 Prints version information to the console.
 456
 457 .SH "SEE ALSO"
 458
 459 .BR dpctl (8),
 460 .BR ofp-discover (8),
 461 .BR controller (8),
 462 .BR ofp-pki (8),
 463 .BR vlogconf (8),
 464 .BR switch (8)