utilities/ovs-openflowd.8.in

   1 .TH ovs\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual"
   2 .\" This program's name:
   3 .ds PN ovs\-openflowd
   4 .\" SSL peer program's name:
   5 .ds SN ovs\-controller
   6 .
   7 .SH NAME
   8 ovs\-openflowd \- OpenFlow switch implementation
   9 .
  10 .SH SYNOPSIS
  11 .B ovs\-openflowd
  12 [\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR\&...]
  13 .
  14 .SH DESCRIPTION
  15 The \fBovs\-openflowd\fR program implements an OpenFlow switch using a
  16 flow-based datapath.  \fBovs\-openflowd\fR connects to one or more
  17 OpenFlow controllers over TCP or SSL.
  18 .PP
  19 For a more powerful alternative to \fBovs\-openflowd\fR, see
  20 \fBovs\-vswitchd\fR(8).  Do not run both daemons at the same time.
  21 .PP
  22 The mandatory \fIdatapath\fR argument argument specifies the local datapath
  23 to relay.  It takes one of the following forms:
  24 .
  25 .so lib/dpif.man
  26 .
  27 .PP
  28 The optional \fIcontroller\fR arguments specify how to connect to the
  29 OpenFlow controller or controllers.  Each takes one of the following
  30 forms:
  31 .
  32 .so lib/vconn-active.man
  33 .
  34 .PP
  35 When multiple controllers are configured, \fBovs\-openflowd\fR
  36 connects to all of them simultaneously.  OpenFlow 1.0 does not specify
  37 how multiple controllers coordinate in interacting with a single
  38 switch, so more than one controller should be specified only if the
  39 controllers are themselves designed to coordinate with each other.
  40 (The Nicira-defined \fBNXT_ROLE\fR OpenFlow vendor extension may be
  41 useful for this.)
  42 .PP
  43 If no \fIcontroller\fR is specified, \fBovs\-openflowd\fR attempts to
  44 discover the location of a controller automatically (see below).
  45 .
  46 .SS "Contacting Controllers"
  47 The OpenFlow switch must be able to contact the OpenFlow controllers
  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 .IP
  56 To use \fBovs\-openflowd\fR in a network with out-of-band control, specify
  57 \fB\-\-out\-of\-band\fR on the \fBovs\-openflowd\fR command line.  The control
  58 network must be configured separately, before or after \fBovs\-openflowd\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 .IP
  69 In-band control is the default for \fBovs\-openflowd\fR, so no special
  70 command-line option is required.
  71 .IP
  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 \fBovs\-openflowd\fR discover the location of the controller
  78 automatically, do not specify a controller on the \fBovs\-openflowd\fR
  79 command line.
  80 .IP
  81 In this mode, \fBovs\-openflowd\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 \fBovs\-openflowd\fR command line (e.g. \fBssl:192.168.0.1\fR).
  88 .IP
  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; \fBovs\-openflowd\fR does not use it at all.
  94 .IP
  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 .IP
 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 \fBovs\-openflowd\fR command line as the \fIcontroller\fR
 148 argument.  You must also configure the network device for the OpenFlow
 149 ``local port'' to allow \fBovs\-openflowd\fR to connect to that controller.
 150 The OpenFlow local port is a virtual network port that \fBovs\-openflowd\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 \fBovs\-openflowd\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 \fBovs\-openflowd\fR.
 164 .IP
 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 OpenFlow switch
 168 has started up.  Thus, start \fBovs\-openflowd\fR without configuring
 169 the local port network device, and start the DHCP client afterward.
 170 .RE
 171 .
 172 .SH OPTIONS
 173 .SS "OpenFlow Options"
 174 .TP
 175 \fB\-\-datapath\-id=\fIdpid\fR
 176 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits,
 177 as the datapath ID that the switch will use to identify itself to
 178 OpenFlow controllers.
 179 .IP
 180 If this option is omitted, the default datapath ID is taken from the
 181 Ethernet address of the datapath's local port (which is typically
 182 randomly generated) in the lower 48 bits and zeros in the upper 16.
 183 .
 184 .TP
 185 \fB\-\-mfr\-desc=\fIdesc\fR
 186 Set the description of the switch's manufacturer to \fIdesc\fR, which
 187 may contain up to 255 ASCII characters.
 188 .
 189 .TP
 190 \fB\-\-hw\-desc=\fIdesc\fR
 191 Set the description of the switch's hardware revision to \fIdesc\fR, which
 192 may contain up to 255 ASCII characters.
 193 .
 194 .TP
 195 \fB\-\-sw\-desc=\fIdesc\fR
 196 Set the description of the switch's software revision to \fIdesc\fR, which
 197 may contain up to 255 ASCII characters.
 198 .
 199 .TP
 200 \fB\-\-serial\-desc=\fIdesc\fR
 201 Set the description of the switch's serial number to \fIdesc\fR, which
 202 may contain up to 31 ASCII characters.
 203 .
 204 .TP
 205 \fB\-\-dp\-desc=\fIdesc\fR
 206 Set the description of the datapath to \fIdesc\fR, which may contain up to
 207 255 ASCII characters.  Note that this field is intended for debugging
 208 purposes and is not guaranteed to be unique and should not be used as
 209 the primary identifier of the datapath.
 210 .
 211 .SS "Controller Discovery Options"
 212 .TP
 213 \fB\-\-accept\-vconn=\fIregex\fR
 214 When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
 215 the Controller\fR, above, for more information about controller
 216 discovery), it validates the controller location obtained via DHCP
 217 with a POSIX extended regular expression.  Only controllers whose
 218 names match the regular expression will be accepted.
 219 .IP
 220 The default regular expression is \fBssl:.*\fR (meaning that only SSL
 221 controller connections will be accepted) when any of the SSL
 222 configuration options \fB\-\-private\-key\fR, \fB\-\-certificate\fR, or
 223 \fB\-\-ca\-cert\fR is specified.  The default is \fB^tcp:.*\fR otherwise
 224 (meaning that only TCP controller connections will be accepted).
 225 .IP
 226 The \fIregex\fR is implicitly anchored at the beginning of the
 227 controller location string, as if it begins with \fB^\fR.
 228 .IP
 229 When controller discovery is not performed, this option has no effect.
 230 .
 231 .TP
 232 \fB\-\-no\-resolv\-conf\fR
 233 When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
 234 the Controller\fR, above, for more information about controller
 235 discovery), by default it overwrites the system's
 236 \fB/etc/resolv.conf\fR with domain information and DNS servers
 237 obtained via DHCP.  If the location of the controller is specified
 238 using a hostname, rather than an IP address, and the network's DNS
 239 servers ever change, this behavior is essential.  But because it also
 240 interferes with any administrator or process that manages
 241 \fB/etc/resolv.conf\fR, when this option is specified, \fBovs\-openflowd\fR
 242 will not modify \fB/etc/resolv.conf\fR.
 243 .IP
 244 \fBovs\-openflowd\fR will only modify \fBresolv.conf\fR if the DHCP response
 245 that it receives specifies one or more DNS servers.
 246 .IP
 247 When controller discovery is not performed, this option has no effect.
 248 .
 249 .SS "Networking Options"
 250 .TP
 251 \fB\-\-datapath\-id=\fIdpid\fR
 252 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits,
 253 as the datapath ID that the switch will use to identify itself to the
 254 OpenFlow controller.
 255 .IP
 256 If this option is omitted, the default datapath ID is taken from the
 257 Ethernet address of the datapath's local port (which is typically
 258 randomly generated) in the lower 48 bits and zeros in the upper 16.
 259 .
 260 .TP
 261 \fB\-\-fail=\fR[\fBstandalone\fR|\fBsecure\fR]
 262 The controller is, ordinarily, responsible for setting up all flows on
 263 the OpenFlow switch.  Thus, if the connection to the controller fails,
 264 no new network connections can be set up.  If the connection to the
 265 controller stays down long enough, no packets can pass through the
 266 switch at all.
 267 .IP
 268 If this option is set to \fBstandalone\fR (the default),
 269 \fBovs\-openflowd\fR will
 270 take over responsibility for setting up flows in the local datapath
 271 when no message has been received from the controller for three times
 272 the inactivity probe interval (see below), or 45 seconds by default.
 273 In this ``fail open'' mode, \fBovs\-openflowd\fR causes the datapath to act
 274 like an ordinary MAC-learning switch.  \fBovs\-openflowd\fR will continue to
 275 retry connection to the controller in the background and, when the
 276 connection succeeds, it discontinues its standalone switching behavior.
 277 .IP
 278 If this option is set to \fBsecure\fR, then \fBovs\-openflowd\fR will not
 279 set up flows on its own when the controller connection fails.
 280 .
 281 .TP
 282 \fB\-\-inactivity\-probe=\fIsecs\fR
 283 When the OpenFlow switch is connected to the controller, the
 284 switch waits for a message to be received from the controller for
 285 \fIsecs\fR seconds before it sends a inactivity probe to the
 286 controller.  After sending the inactivity probe, if no response is
 287 received for an additional \fIsecs\fR seconds, the switch
 288 assumes that the connection has been broken and attempts to reconnect.
 289 The default and the minimum value are both 5 seconds.
 290 .IP
 291 When fail-open mode is configured, changing the inactivity probe
 292 interval also changes the interval before entering fail-open mode (see
 293 above).
 294 .
 295 .TP
 296 \fB\-\-max\-idle=\fIsecs\fR|\fBpermanent\fR
 297 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 298 OpenFlow switch will remain in the switch's flow table without any
 299 matching packets being seen.  If \fBpermanent\fR is specified, which
 300 is not recommended, flows set up by the switch will never
 301 expire.  The default is 15 seconds.
 302 .IP
 303 Most flows are set up by the OpenFlow controller, not by the
 304 switch.  This option affects only the following flows, which the
 305 OpenFlow switch sets up itself:
 306 .
 307 .RS
 308 .IP \(bu
 309 When \fB\-\-fail=open\fR is specified, flows set up when the
 310 switch has not been able to contact the controller for the configured
 311 fail-open delay.
 312 .
 313 .IP \(bu
 314 When in-band control is in use, flows set up to bootstrap contacting
 315 the controller (see \fBContacting the Controller\fR, above, for
 316 more information about in-band control).
 317 .RE
 318 .
 319 .IP
 320 As a result, when both \fB\-\-fail=secure\fR and \fB\-\-out\-of\-band\fR are
 321 specified, this option has no effect.
 322 .
 323 .TP
 324 \fB\-\-max\-backoff=\fIsecs\fR
 325 Sets the maximum time between attempts to connect to the controller to
 326 \fIsecs\fR, which must be at least 1.  The actual interval between
 327 connection attempts starts at 1 second and doubles on each failing
 328 attempt until it reaches the maximum.  The default maximum backoff
 329 time is 8 seconds.
 330 .
 331 .TP
 332 \fB\-l\fR, \fB\-\-listen=\fImethod\fR
 333 By default, the switch listens for OpenFlow management connections on a
 334 Unix domain socket named \fB@RUNDIR@/\fIdatapath\fB.mgmt\fR.  This socket
 335 can be used to perform local OpenFlow monitoring and administration with
 336 tools such as \fBovs\-ofctl\fR.
 337 .IP
 338 This option may be used to override the default listener.  The \fImethod\fR
 339 must be given as one of the passive OpenFlow connection methods listed
 340 below.  This option may be specified multiple times to listen to
 341 multiple connection methods.  If a single \fImethod\fR of \fBnone\fR is
 342 used, no listeners will be created.
 343 .
 344 .RS
 345 .so lib/vconn-passive.man
 346 .RE
 347 .
 348 .TP
 349 \fB\-\-snoop=\fImethod\fR
 350 Configures the switch to additionally listen for incoming OpenFlow
 351 connections for controller connection snooping.  The \fImethod\fR must
 352 be given as one of the passive OpenFlow connection methods listed
 353 under the \fB\-\-listen\fR option above.  This option may be specified
 354 multiple times to listen to multiple connection methods.
 355 .IP
 356 If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on
 357 \fB\-\-snoop\fR, it will display all the OpenFlow messages traveling
 358 between the switch and its controller on the primary OpenFlow
 359 connection.  This can be useful for debugging switch and controller
 360 problems.
 361 .
 362 .TP
 363 \fB\-\-in\-band\fR, \fB\-\-out\-of\-band\fR
 364 Configures \fBovs\-openflowd\fR to operate in in-band or out-of-band control
 365 mode (see \fBContacting the Controller\fR above).  When neither option
 366 is given, the default is in-band control.
 367 .
 368 .TP
 369 \fB\-\-netflow=\fIip\fB:\fIport\fR
 370 Configures the given UDP \fIport\fR on the specified IP \fIip\fR as
 371 a recipient of NetFlow messages for expired flows.  The \fIip\fR must
 372 be specified numerically, not as a DNS name.
 373 .IP
 374 This option may be specified multiple times to configure additional
 375 NetFlow collectors.
 376 .
 377 .SS "Rate-Limiting Options"
 378 .
 379 These options configure how the switch applies a ``token bucket'' to
 380 limit the rate at which packets in unknown flows are forwarded to an
 381 OpenFlow controller for flow-setup processing.  This feature prevents
 382 a single OpenFlow switch from overwhelming a controller.
 383 .
 384 .TP
 385 \fB\-\-rate\-limit\fR[\fB=\fIrate\fR]
 386 .
 387 Limits the maximum rate at which packets will be forwarded to the
 388 OpenFlow controller to \fIrate\fR packets per second.  If \fIrate\fR
 389 is not specified then the default of 1,000 packets per second is used.
 390 .IP
 391 If \fB\-\-rate\-limit\fR is not used, then the switch does not limit the
 392 rate at which packets are forwarded to the controller.
 393 .
 394 .TP
 395 \fB\-\-burst\-limit=\fIburst\fR
 396 .
 397 Sets the maximum number of unused packet credits that the switch will
 398 allow to accumulate during time in which no packets are being
 399 forwarded to the OpenFlow controller to \fIburst\fR (measured in
 400 packets).  The default \fIburst\fR is one-quarter of the \fIrate\fR
 401 specified on \fB\-\-rate\-limit\fR.
 402 .
 403 This option takes effect only when \fB\-\-rate\-limit\fR is also specified.
 404 .
 405 .SS "Datapath Options"
 406 .
 407 .IP "\fB\-\-ports=\fIport\fR[\fB,\fIport\fR...]"
 408 Ordinarily, \fBovs\-openflowd\fR expects the administrator to create
 409 the specified \fIdatapath\fR and add ports to it externally with a
 410 utility such as \fBovs\-dpctl\fR.  However, the userspace switch
 411 datapath is implemented inside \fBovs\-openflowd\fR itself and does
 412 not (currently) have any external interface for \fBovs\-dpctl\fR to
 413 access.  As a stopgap measure, this option specifies one or more ports
 414 to add to the datapath at \fBovs\-openflowd\fR startup time.  Multiple
 415 ports may be specified as a comma-separated list or by specifying
 416 \fB\-\-ports\fR multiple times.
 417 .IP
 418 See \fBINSTALL.userspace\fR for more information about userspace
 419 switching.
 420 .
 421 .SS "Daemon Options"
 422 .so lib/daemon.man
 423 .
 424 .SS "Public Key Infrastructure Options"
 425 .so lib/ssl.man
 426 .so lib/ssl-bootstrap.man
 427 .
 428 .SS "Logging Options"
 429 .so lib/vlog.man
 430 .SS "Other Options"
 431 .so lib/common.man
 432 .so lib/leak-checker.man
 433 .
 434 .SH "SEE ALSO"
 435 .
 436 .BR ovs\-appctl (8),
 437 .BR ovs\-controller (8),
 438 .BR ovs\-discover (8),
 439 .BR ovs\-dpctl (8),
 440 .BR ovs\-ofctl (8),
 441 .BR ovs\-pki (8)