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