.TH test\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual" .\" This program's name: .ds PN test\-openflowd .\" SSL peer program's name: .ds SN ovs\-controller . .SH NAME test\-openflowd \- OpenFlow switch implementation . .SH SYNOPSIS .B test\-openflowd [\fIoptions\fR] \fIdatapath\fR \fIcontroller\fR\&... . .SH DESCRIPTION The \fBtest\-openflowd\fR program implements an OpenFlow switch using a flow-based datapath. \fBtest\-openflowd\fR connects to one or more OpenFlow controllers over TCP or SSL. .PP For a more powerful alternative to \fBtest\-openflowd\fR, see \fBovs\-vswitchd\fR(8). Do not run both daemons at the same time. .PP The mandatory \fIdatapath\fR argument argument specifies the local datapath to relay. It takes the form [\fItype\fB@\fR]\fIname\fR, where \fIname\fR is the network device associated with the datapath's local port. If \fItype\fR is given, it specifies the datapath provider of \fIname\fR, otherwise the default provider \fBsystem\fR is assumed. . .PP The optional \fIcontroller\fR arguments specify how to connect to the OpenFlow controller or controllers. Each takes one of the following forms: . .so lib/vconn-active.man .IP "\fBnone\fR" Run without actively maintaining a connection to a remote OpenFlow controller. (See the \fB\-\-listen\fR option, under \fBNetworking Options\fR below, for another way to make OpenFlow connections to the switch.) . .PP When multiple controllers are configured, \fBtest\-openflowd\fR connects to all of them simultaneously. OpenFlow 1.0 does not specify how multiple controllers coordinate in interacting with a single switch, so more than one controller should be specified only if the controllers are themselves designed to coordinate with each other. (The Nicira-defined \fBNXT_ROLE\fR OpenFlow vendor extension may be useful for this.) . .SS "Contacting Controllers" The OpenFlow switch must be able to contact the OpenFlow controllers over the network. It can do so in one of two ways: . .IP out-of-band In this configuration, OpenFlow traffic uses a network separate from the data traffic that it controls, that is, the switch does not use any of the network devices added to the datapath with \fBovs\-dpctl add\-if\fR in its communication with the controller. .IP To use \fBtest\-openflowd\fR in a network with out-of-band control, specify \fB\-\-out\-of\-band\fR on the \fBtest\-openflowd\fR command line. The control network must be configured separately, before or after \fBtest\-openflowd\fR is started. . .IP in-band In this configuration, a single network is used for OpenFlow traffic and other data traffic, that is, the switch contacts the controller over one of the network devices added to the datapath with \fBovs\-dpctl add\-if\fR. This configuration is often more convenient than out-of-band control, because it is not necessary to maintain two independent networks. .IP In-band control is the default for \fBtest\-openflowd\fR, so no special command-line option is required. Specify the location of the controller on the \fBtest\-openflowd\fR command line as the \fIcontroller\fR argument. You must also configure the network device for the OpenFlow ``local port'' to allow \fBtest\-openflowd\fR to connect to that controller. The OpenFlow local port is a virtual network port that \fBtest\-openflowd\fR bridges to the physical switch ports. The name of the local port for a given \fIdatapath\fR may be seen by running \fBovs\-dpctl show \fIdatapath\fR; the local port is listed as port 0 in \fBshow\fR's output. . .IP Before \fBtest\-openflowd\fR starts, the local port network device is not bridged to any physical network, so the next step depends on whether connectivity is required to configure the device's IP address. If the switch has a static IP address, you may configure its IP address now with a command such as .B ifconfig of0 192.168.1.1 and then invoke \fBtest\-openflowd\fR. .IP On the other hand, if the switch does not have a static IP address, e.g. it obtains its IP address dynamically via DHCP, the DHCP client will not be able to contact the DHCP server until the OpenFlow switch has started up. Thus, start \fBtest\-openflowd\fR without configuring the local port network device, and start the DHCP client afterward. .RE . .SH OPTIONS .SS "OpenFlow Options" .TP \fB\-\-datapath\-id=\fIdpid\fR Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits and may not be all-zero, as the datapath ID that the switch will use to identify itself to OpenFlow controllers. .IP If this option is omitted, the default datapath ID is taken from the Ethernet address of the datapath's local port (which is typically randomly generated) in the lower 48 bits and zeros in the upper 16. . .TP \fB\-\-mfr\-desc=\fIdesc\fR Set the description of the switch's manufacturer to \fIdesc\fR, which may contain up to 255 ASCII characters. . .TP \fB\-\-hw\-desc=\fIdesc\fR Set the description of the switch's hardware revision to \fIdesc\fR, which may contain up to 255 ASCII characters. . .TP \fB\-\-sw\-desc=\fIdesc\fR Set the description of the switch's software revision to \fIdesc\fR, which may contain up to 255 ASCII characters. . .TP \fB\-\-serial\-desc=\fIdesc\fR Set the description of the switch's serial number to \fIdesc\fR, which may contain up to 31 ASCII characters. . .TP \fB\-\-dp\-desc=\fIdesc\fR Set the description of the datapath to \fIdesc\fR, which may contain up to 255 ASCII characters. Note that this field is intended for debugging purposes and is not guaranteed to be unique and should not be used as the primary identifier of the datapath. . .SS "Networking Options" .TP \fB\-\-datapath\-id=\fIdpid\fR Sets \fIdpid\fR, which must consist of exactly 16 hexadecimal digits, as the datapath ID that the switch will use to identify itself to the OpenFlow controller. .IP If this option is omitted, the default datapath ID is taken from the Ethernet address of the datapath's local port (which is typically randomly generated) in the lower 48 bits and zeros in the upper 16. . .TP \fB\-\-fail=\fR[\fBstandalone\fR|\fBsecure\fR] The controller is, ordinarily, responsible for setting up all flows on the OpenFlow switch. Thus, if the connection to the controller fails, no new network connections can be set up. If the connection to the controller stays down long enough, no packets can pass through the switch at all. .IP If this option is set to \fBstandalone\fR (the default), \fBtest\-openflowd\fR will take over responsibility for setting up flows in the local datapath when no message has been received from the controller for three times the inactivity probe interval (see below), or 45 seconds by default. In this ``fail open'' mode, \fBtest\-openflowd\fR causes the datapath to act like an ordinary MAC-learning switch. \fBtest\-openflowd\fR will continue to retry connection to the controller in the background and, when the connection succeeds, it discontinues its standalone switching behavior. .IP If this option is set to \fBsecure\fR, then \fBtest\-openflowd\fR will not set up flows on its own when the controller connection fails. . .TP \fB\-\-inactivity\-probe=\fIsecs\fR When the OpenFlow switch is connected to the controller, the switch waits for a message to be received from the controller for \fIsecs\fR seconds before it sends a inactivity probe to the controller. After sending the inactivity probe, if no response is received for an additional \fIsecs\fR seconds, the switch assumes that the connection has been broken and attempts to reconnect. The default and the minimum value are both 5 seconds. .IP When fail-open mode is configured, changing the inactivity probe interval also changes the interval before entering fail-open mode (see above). . .TP \fB\-\-max\-idle=\fIsecs\fR|\fBpermanent\fR Sets \fIsecs\fR as the number of seconds that a flow set up by the OpenFlow switch will remain in the switch's flow table without any matching packets being seen. If \fBpermanent\fR is specified, which is not recommended, flows set up by the switch will never expire. The default is 15 seconds. .IP Most flows are set up by the OpenFlow controller, not by the switch. This option affects only the following flows, which the OpenFlow switch sets up itself: . .RS .IP \(bu When \fB\-\-fail=open\fR is specified, flows set up when the switch has not been able to contact the controller for the configured fail-open delay. . .IP \(bu When in-band control is in use, flows set up to bootstrap contacting the controller (see \fBContacting the Controller\fR, above, for more information about in-band control). .RE . .IP As a result, when both \fB\-\-fail=secure\fR and \fB\-\-out\-of\-band\fR are specified, this option has no effect. . .TP \fB\-\-max\-backoff=\fIsecs\fR Sets the maximum time between attempts to connect to the controller to \fIsecs\fR, which must be at least 1. The actual interval between connection attempts starts at 1 second and doubles on each failing attempt until it reaches the maximum. The default maximum backoff time is 8 seconds. . .TP \fB\-l\fR, \fB\-\-listen=\fImethod\fR By default, the switch listens for OpenFlow management connections on a Unix domain socket named \fB@RUNDIR@/\fIdatapath\fB.mgmt\fR. This socket can be used to perform local OpenFlow monitoring and administration with tools such as \fBovs\-ofctl\fR. .IP This option may be used to override the default listener. The \fImethod\fR must be given as one of the passive OpenFlow connection methods listed below. This option may be specified multiple times to listen to multiple connection methods. If a single \fImethod\fR of \fBnone\fR is used, no listeners will be created. . .RS .so lib/vconn-passive.man .RE . .TP \fB\-\-snoop=\fImethod\fR Configures the switch to additionally listen for incoming OpenFlow connections for controller connection snooping. The \fImethod\fR must be given as one of the passive OpenFlow connection methods listed under the \fB\-\-listen\fR option above. This option may be specified multiple times to listen to multiple connection methods. .IP If \fBovs\-ofctl monitor\fR is used to connect to \fImethod\fR specified on \fB\-\-snoop\fR, it will display all the OpenFlow messages traveling between the switch and its controller on the primary OpenFlow connection. This can be useful for debugging switch and controller problems. . .TP \fB\-\-in\-band\fR, \fB\-\-out\-of\-band\fR Configures \fBtest\-openflowd\fR to operate in in-band or out-of-band control mode (see \fBContacting the Controller\fR above). When neither option is given, the default is in-band control. . .TP \fB\-\-netflow=\fIip\fB:\fIport\fR Configures the given UDP \fIport\fR on the specified IP \fIip\fR as a recipient of NetFlow messages for expired flows. The \fIip\fR must be specified numerically, not as a DNS name. .IP This option may be specified multiple times to configure additional NetFlow collectors. . .SS "Rate-Limiting Options" . These options configure how the switch applies a ``token bucket'' to limit the rate at which packets in unknown flows are forwarded to an OpenFlow controller for flow-setup processing. This feature prevents a single OpenFlow switch from overwhelming a controller. . .TP \fB\-\-rate\-limit\fR[\fB=\fIrate\fR] . Limits the maximum rate at which packets will be forwarded to the OpenFlow controller to \fIrate\fR packets per second. If \fIrate\fR is not specified then the default of 1,000 packets per second is used. .IP If \fB\-\-rate\-limit\fR is not used, then the switch does not limit the rate at which packets are forwarded to the controller. . .TP \fB\-\-burst\-limit=\fIburst\fR . Sets the maximum number of unused packet credits that the switch will allow to accumulate during time in which no packets are being forwarded to the OpenFlow controller to \fIburst\fR (measured in packets). The default \fIburst\fR is one-quarter of the \fIrate\fR specified on \fB\-\-rate\-limit\fR. . This option takes effect only when \fB\-\-rate\-limit\fR is also specified. . .SS "Datapath Options" . .IP "\fB\-\-ports=\fIport\fR[\fB,\fIport\fR...]" Ordinarily, \fBtest\-openflowd\fR expects the administrator to create the specified \fIdatapath\fR and add ports to it externally with a utility such as \fBovs\-dpctl\fR. However, the userspace switch datapath is implemented inside \fBtest\-openflowd\fR itself and does not (currently) have any external interface for \fBovs\-dpctl\fR to access. As a stopgap measure, this option specifies one or more ports to add to the datapath at \fBtest\-openflowd\fR startup time. Multiple ports may be specified as a comma-separated list or by specifying \fB\-\-ports\fR multiple times. .IP See \fBINSTALL.userspace\fR for more information about userspace switching. . .SS "Daemon Options" .so lib/daemon.man . .SS "Public Key Infrastructure Options" .so lib/ssl.man .so lib/ssl-bootstrap.man . .SS "Logging Options" .so lib/vlog.man .SS "Other Options" .so lib/unixctl.man .so lib/common.man .so lib/leak-checker.man . .SH "RUNTIME MANAGEMENT COMMANDS" \fBovs\-appctl\fR(8) can send commands to a running \fBtest\-openflowd\fR process. The currently supported commands are described below. .SS "TEST\-OPENFLOWD COMMANDS" These commands are specific to \fBtest\-openflowd\fR. .IP "\fBexit\fR" Causes \fBtest\-openflowd\fR to gracefully terminate. .so ofproto/ofproto-unixctl.man .so lib/vlog-unixctl.man . .SH "SEE ALSO" . .BR ovs\-appctl (8), .BR ovs\-controller (8), .BR ovs\-dpctl (8), .BR ovs\-ofctl (8), .BR ovs\-pki (8)