secchan/secchan.8.in

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