utilities/ovs-openflowd.8.in

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