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