ovs-openflowd: Rename test-openflowd and move to "tests" directory.

Too many users thought that they needed to run ovs-openflowd at the same
time as ovs-vswitchd.  I hope that this change discourages them.

1 files changed, 345 insertions, 0 deletions

diff --git a/tests/test-openflowd.8.in b/tests/test-openflowd.8.in
new file mode 100644
index 000000000..135ba846e
--- /dev/null
+++ b/tests/test-openflowd.8.in
@@ -0,0 +1,345 @@
+.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)