pintos-os.org Git - openvswitch/blob - tests/test-openflowd.8.in

   1 .TH test\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual"
   2 .\" This program's name:
   3 .ds PN test\-openflowd
   4 .\" SSL peer program's name:
   5 .ds SN ovs\-controller
   6 .
   7 .SH NAME
   8 test\-openflowd \- OpenFlow switch implementation
   9 .
  10 .SH SYNOPSIS
  11 .B test\-openflowd
  12 [\fIoptions\fR] \fIdatapath\fR \fIcontroller\fR\&...
  13 .
  14 .SH DESCRIPTION
  15 The \fBtest\-openflowd\fR program implements an OpenFlow switch using a
  16 flow-based datapath.  \fBtest\-openflowd\fR connects to one or more
  17 OpenFlow controllers over TCP or SSL.
  18 .PP
  19 For a more powerful alternative to \fBtest\-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, \fBtest\-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 .
  50 .SS "Contacting Controllers"
  51 The OpenFlow switch must be able to contact the OpenFlow controllers
  52 over the network.  It can do so in one of two ways:
  53 .
  54 .IP out-of-band
  55 In this configuration, OpenFlow traffic uses a network separate from
  56 the data traffic that it controls, that is, the switch does not use
  57 any of the network devices added to the datapath with \fBovs\-dpctl
  58 add\-if\fR in its communication with the controller.
  59 .IP
  60 To use \fBtest\-openflowd\fR in a network with out-of-band control, specify
  61 \fB\-\-out\-of\-band\fR on the \fBtest\-openflowd\fR command line.  The control
  62 network must be configured separately, before or after \fBtest\-openflowd\fR
  63 is started.
  64 .
  65 .IP in-band
  66 In this configuration, a single network is used for OpenFlow traffic
  67 and other data traffic, that is, the switch contacts the controller
  68 over one of the network devices added to the datapath with \fBovs\-dpctl
  69 add\-if\fR.  This configuration is often more convenient than
  70 out-of-band control, because it is not necessary to maintain two
  71 independent networks.
  72 .IP
  73 In-band control is the default for \fBtest\-openflowd\fR, so no special
  74 command-line option is required.
  75
  76 Specify the location of the
  77 controller on the \fBtest\-openflowd\fR command line as the \fIcontroller\fR
  78 argument.  You must also configure the network device for the OpenFlow
  79 ``local port'' to allow \fBtest\-openflowd\fR to connect to that controller.
  80 The OpenFlow local port is a virtual network port that \fBtest\-openflowd\fR
  81 bridges to the physical switch ports.  The name of the local port for
  82 a given \fIdatapath\fR may be seen by running \fBovs\-dpctl show
  83 \fIdatapath\fR; the local port is listed as port 0 in \fBshow\fR's
  84 output.
  85 .
  86 .IP
  87 Before \fBtest\-openflowd\fR starts, the local port network device is not
  88 bridged to any physical network, so the next step depends on whether
  89 connectivity is required to configure the device's IP address.  If the
  90 switch has a static IP address, you may configure its IP address now
  91 with a command such as
  92 .B ifconfig of0 192.168.1.1
  93 and then invoke \fBtest\-openflowd\fR.
  94 .IP
  95 On the other hand, if the switch does not have a static IP address,
  96 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
  97 will not be able to contact the DHCP server until the OpenFlow switch
  98 has started up.  Thus, start \fBtest\-openflowd\fR without configuring
  99 the local port network device, and start the DHCP client afterward.
 100 .RE
 101 .
 102 .SH OPTIONS
 103 .SS "OpenFlow Options"
 104 .TP
 105 \fB\-\-datapath\-id=\fIdpid\fR
 106 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits
 107 and may not be all-zero,
 108 as the datapath ID that the switch will use to identify itself to
 109 OpenFlow controllers.
 110 .IP
 111 If this option is omitted, the default datapath ID is taken from the
 112 Ethernet address of the datapath's local port (which is typically
 113 randomly generated) in the lower 48 bits and zeros in the upper 16.
 114 .
 115 .TP
 116 \fB\-\-mfr\-desc=\fIdesc\fR
 117 Set the description of the switch's manufacturer to \fIdesc\fR, which
 118 may contain up to 255 ASCII characters.
 119 .
 120 .TP
 121 \fB\-\-hw\-desc=\fIdesc\fR
 122 Set the description of the switch's hardware revision to \fIdesc\fR, which
 123 may contain up to 255 ASCII characters.
 124 .
 125 .TP
 126 \fB\-\-sw\-desc=\fIdesc\fR
 127 Set the description of the switch's software revision to \fIdesc\fR, which
 128 may contain up to 255 ASCII characters.
 129 .
 130 .TP
 131 \fB\-\-serial\-desc=\fIdesc\fR
 132 Set the description of the switch's serial number to \fIdesc\fR, which
 133 may contain up to 31 ASCII characters.
 134 .
 135 .TP
 136 \fB\-\-dp\-desc=\fIdesc\fR
 137 Set the description of the datapath to \fIdesc\fR, which may contain up to
 138 255 ASCII characters.  Note that this field is intended for debugging
 139 purposes and is not guaranteed to be unique and should not be used as
 140 the primary identifier of the datapath.
 141 .
 142 .SS "Networking Options"
 143 .TP
 144 \fB\-\-datapath\-id=\fIdpid\fR
 145 Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits,
 146 as the datapath ID that the switch will use to identify itself to the
 147 OpenFlow controller.
 148 .IP
 149 If this option is omitted, the default datapath ID is taken from the
 150 Ethernet address of the datapath's local port (which is typically
 151 randomly generated) in the lower 48 bits and zeros in the upper 16.
 152 .
 153 .TP
 154 \fB\-\-fail=\fR[\fBstandalone\fR|\fBsecure\fR]
 155 The controller is, ordinarily, responsible for setting up all flows on
 156 the OpenFlow switch.  Thus, if the connection to the controller fails,
 157 no new network connections can be set up.  If the connection to the
 158 controller stays down long enough, no packets can pass through the
 159 switch at all.
 160 .IP
 161 If this option is set to \fBstandalone\fR (the default),
 162 \fBtest\-openflowd\fR will
 163 take over responsibility for setting up flows in the local datapath
 164 when no message has been received from the controller for three times
 165 the inactivity probe interval (see below), or 45 seconds by default.
 166 In this ``fail open'' mode, \fBtest\-openflowd\fR causes the datapath to act
 167 like an ordinary MAC-learning switch.  \fBtest\-openflowd\fR will continue to
 168 retry connection to the controller in the background and, when the
 169 connection succeeds, it discontinues its standalone switching behavior.
 170 .IP
 171 If this option is set to \fBsecure\fR, then \fBtest\-openflowd\fR will not
 172 set up flows on its own when the controller connection fails.
 173 .
 174 .TP
 175 \fB\-\-inactivity\-probe=\fIsecs\fR
 176 When the OpenFlow switch is connected to the controller, the
 177 switch waits for a message to be received from the controller for
 178 \fIsecs\fR seconds before it sends a inactivity probe to the
 179 controller.  After sending the inactivity probe, if no response is
 180 received for an additional \fIsecs\fR seconds, the switch
 181 assumes that the connection has been broken and attempts to reconnect.
 182 The default and the minimum value are both 5 seconds.
 183 .IP
 184 When fail-open mode is configured, changing the inactivity probe
 185 interval also changes the interval before entering fail-open mode (see
 186 above).
 187 .
 188 .TP
 189 \fB\-\-max\-idle=\fIsecs\fR|\fBpermanent\fR
 190 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 191 OpenFlow switch will remain in the switch's flow table without any
 192 matching packets being seen.  If \fBpermanent\fR is specified, which
 193 is not recommended, flows set up by the switch will never
 194 expire.  The default is 15 seconds.
 195 .IP
 196 Most flows are set up by the OpenFlow controller, not by the
 197 switch.  This option affects only the following flows, which the
 198 OpenFlow switch sets up itself:
 199 .
 200 .RS
 201 .IP \(bu
 202 When \fB\-\-fail=open\fR is specified, flows set up when the
 203 switch has not been able to contact the controller for the configured
 204 fail-open delay.
 205 .
 206 .IP \(bu
 207 When in-band control is in use, flows set up to bootstrap contacting
 208 the controller (see \fBContacting the Controller\fR, above, for
 209 more information about in-band control).
 210 .RE
 211 .
 212 .IP
 213 As a result, when both \fB\-\-fail=secure\fR and \fB\-\-out\-of\-band\fR are
 214 specified, this option has no effect.
 215 .
 216 .TP
 217 \fB\-\-max\-backoff=\fIsecs\fR
 218 Sets the maximum time between attempts to connect to the controller to
 219 \fIsecs\fR, which must be at least 1.  The actual interval between
 220 connection attempts starts at 1 second and doubles on each failing
 221 attempt until it reaches the maximum.  The default maximum backoff
 222 time is 8 seconds.
 223 .
 224 .TP
 225 \fB\-l\fR, \fB\-\-listen=\fImethod\fR
 226 By default, the switch listens for OpenFlow management connections on a
 227 Unix domain socket named \fB@RUNDIR@/\fIdatapath\fB.mgmt\fR.  This socket
 228 can be used to perform local OpenFlow monitoring and administration with
 229 tools such as \fBovs\-ofctl\fR.
 230 .IP
 231 This option may be used to override the default listener.  The \fImethod\fR
 232 must be given as one of the passive OpenFlow connection methods listed
 233 below.  This option may be specified multiple times to listen to
 234 multiple connection methods.  If a single \fImethod\fR of \fBnone\fR is
 235 used, no listeners will be created.
 236 .
 237 .RS
 238 .so lib/vconn-passive.man
 239 .RE
 240 .
 241 .TP
 242 \fB\-\-snoop=\fImethod\fR
 243 Configures the switch to additionally listen for incoming OpenFlow
 244 connections for controller connection snooping.  The \fImethod\fR must
 245 be given as one of the passive OpenFlow connection methods listed
 246 under the \fB\-\-listen\fR option above.  This option may be specified
 247 multiple times to listen to multiple connection methods.
 248 .IP
 249 If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on
 250 \fB\-\-snoop\fR, it will display all the OpenFlow messages traveling
 251 between the switch and its controller on the primary OpenFlow
 252 connection.  This can be useful for debugging switch and controller
 253 problems.
 254 .
 255 .TP
 256 \fB\-\-in\-band\fR, \fB\-\-out\-of\-band\fR
 257 Configures \fBtest\-openflowd\fR to operate in in-band or out-of-band control
 258 mode (see \fBContacting the Controller\fR above).  When neither option
 259 is given, the default is in-band control.
 260 .
 261 .TP
 262 \fB\-\-netflow=\fIip\fB:\fIport\fR
 263 Configures the given UDP \fIport\fR on the specified IP \fIip\fR as
 264 a recipient of NetFlow messages for expired flows.  The \fIip\fR must
 265 be specified numerically, not as a DNS name.
 266 .IP
 267 This option may be specified multiple times to configure additional
 268 NetFlow collectors.
 269 .
 270 .SS "Rate-Limiting Options"
 271 .
 272 These options configure how the switch applies a ``token bucket'' to
 273 limit the rate at which packets in unknown flows are forwarded to an
 274 OpenFlow controller for flow-setup processing.  This feature prevents
 275 a single OpenFlow switch from overwhelming a controller.
 276 .
 277 .TP
 278 \fB\-\-rate\-limit\fR[\fB=\fIrate\fR]
 279 .
 280 Limits the maximum rate at which packets will be forwarded to the
 281 OpenFlow controller to \fIrate\fR packets per second.  If \fIrate\fR
 282 is not specified then the default of 1,000 packets per second is used.
 283 .IP
 284 If \fB\-\-rate\-limit\fR is not used, then the switch does not limit the
 285 rate at which packets are forwarded to the controller.
 286 .
 287 .TP
 288 \fB\-\-burst\-limit=\fIburst\fR
 289 .
 290 Sets the maximum number of unused packet credits that the switch will
 291 allow to accumulate during time in which no packets are being
 292 forwarded to the OpenFlow controller to \fIburst\fR (measured in
 293 packets).  The default \fIburst\fR is one-quarter of the \fIrate\fR
 294 specified on \fB\-\-rate\-limit\fR.
 295 .
 296 This option takes effect only when \fB\-\-rate\-limit\fR is also specified.
 297 .
 298 .SS "Datapath Options"
 299 .
 300 .IP "\fB\-\-ports=\fIport\fR[\fB,\fIport\fR...]"
 301 Ordinarily, \fBtest\-openflowd\fR expects the administrator to create
 302 the specified \fIdatapath\fR and add ports to it externally with a
 303 utility such as \fBovs\-dpctl\fR.  However, the userspace switch
 304 datapath is implemented inside \fBtest\-openflowd\fR itself and does
 305 not (currently) have any external interface for \fBovs\-dpctl\fR to
 306 access.  As a stopgap measure, this option specifies one or more ports
 307 to add to the datapath at \fBtest\-openflowd\fR startup time.  Multiple
 308 ports may be specified as a comma-separated list or by specifying
 309 \fB\-\-ports\fR multiple times.
 310 .IP
 311 See \fBINSTALL.userspace\fR for more information about userspace
 312 switching.
 313 .
 314 .SS "Daemon Options"
 315 .so lib/daemon.man
 316 .
 317 .SS "Public Key Infrastructure Options"
 318 .so lib/ssl.man
 319 .so lib/ssl-bootstrap.man
 320 .
 321 .SS "Logging Options"
 322 .so lib/vlog.man
 323 .SS "Other Options"
 324 .so lib/unixctl.man
 325 .so lib/common.man
 326 .so lib/leak-checker.man
 327 .
 328 .SH "RUNTIME MANAGEMENT COMMANDS"
 329 \fBovs\-appctl\fR(8) can send commands to a running
 330 \fBtest\-openflowd\fR process.  The currently supported commands are
 331 described below.
 332 .SS "TEST\-OPENFLOWD COMMANDS"
 333 These commands are specific to \fBtest\-openflowd\fR.
 334 .IP "\fBexit\fR"
 335 Causes \fBtest\-openflowd\fR to gracefully terminate.
 336 .so ofproto/ofproto-unixctl.man
 337 .so lib/vlog-unixctl.man
 338 .
 339 .SH "SEE ALSO"
 340 .
 341 .BR ovs\-appctl (8),
 342 .BR ovs\-controller (8),
 343 .BR ovs\-dpctl (8),
 344 .BR ovs\-ofctl (8),
 345 .BR ovs\-pki (8)