--- /dev/null
- .TP
- \fBssl:\fIhost\fR[\fB:\fIport\fR]
- The specified SSL \fIport\fR (default: 6633) on the given remote
- \fIhost\fR. The \fB--private-key\fR, \fB--certificate\fR, and
- \fB--ca-cert\fR options are mandatory when this form is used.
+.TH ovs\-openflowd 8 "March 2009" "Open vSwitch" "Open vSwitch Manual"
+.ds PN ovs\-openflowd
+
+.SH NAME
+ovs\-openflowd \- OpenFlow switch implementation
+
+.SH SYNOPSIS
+.B ovs\-openflowd
+[\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR]
+
+.SH DESCRIPTION
+The \fBovs\-openflowd\fR program implements an OpenFlow switch using a
+flow-based datapath. \fBovs\-openflowd\fR connects to an OpenFlow controller
+over TCP or SSL.
+
+The mandatory \fIdatapath\fR argument argument specifies the local datapath
+to relay. It takes one of the following forms:
+
+.so lib/dpif.man
+
+.PP
+The optional \fIcontroller\fR argument specifies how to connect to
+the OpenFlow controller. It takes one of the following forms:
+
+.RS
- .TP
- \fBtcp:\fIhost\fR[\fB:\fIport\fR]
- The specified TCP \fIport\fR (default: 6633) on the given remote
- \fIhost\fR.
++.IP "\fBssl:\fIip\fR[\fB:\fIport\fR]"
++The specified SSL \fIport\fR (default: 6633) on the host at the given
++\fIip\fR, which must be expressed as an IP address (not a DNS name).
++The \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR
++options are mandatory when this form is used.
+
- \fB--netflow=\fIhost\fB:\fIport\fR
- Configures the given UDP \fIport\fR on the specified IP \fIhost\fR as
- a recipient of NetFlow messages for expired flows.
++.IP "\fBtcp:\fIip\fR[\fB:\fIport\fR]"
++The specified TCP \fIport\fR (default: 6633) on the host at the given
++\fIip\fR, which must be expressed as an IP address (not a DNS name).
+
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.
+.RE
+
+.PP
+If \fIcontroller\fR is omitted, \fBovs\-openflowd\fR attempts to discover the
+location of the controller automatically (see below).
+
+.SS "Contacting the Controller"
+The OpenFlow switch must be able to contact the OpenFlow controller
+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.
+
+To use \fBovs\-openflowd\fR in a network with out-of-band control, specify
+\fB--out-of-band\fR on the \fBovs\-openflowd\fR command line. The control
+network must be configured separately, before or after \fBovs\-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.
+
+In-band control is the default for \fBovs\-openflowd\fR, so no special
+command-line option is required.
+
+With in-band control, the location of the controller can be configured
+manually or discovered automatically:
+
+.RS
+.IP "controller discovery"
+To make \fBovs\-openflowd\fR discover the location of the controller
+automatically, do not specify the location of the controller on the
+\fBovs\-openflowd\fR command line.
+
+In this mode, \fBovs\-openflowd\fR will broadcast a DHCP request with vendor
+class identifier \fBOpenFlow\fR across the network devices added to
+the datapath with \fBovs\-dpctl add\-if\fR. It will accept any valid DHCP
+reply that has the same vendor class identifier and includes a
+vendor-specific option with code 1 whose contents are a string
+specifying the location of the controller in the same format used on
+the \fBovs\-openflowd\fR command line (e.g. \fBssl:192.168.0.1\fR).
+
+The DHCP reply may also, optionally, include a vendor-specific option
+with code 2 whose contents are a string specifying the URI to the base
+of the OpenFlow PKI (e.g. \fBhttp://192.168.0.1/openflow/pki\fR).
+This URI is used only for bootstrapping the OpenFlow PKI at initial
+switch setup; \fBovs\-openflowd\fR does not use it at all.
+
+The following ISC DHCP server configuration file assigns the IP
+address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
+that follow the switch protocol and addresses 192.168.0.1 through
+192.168.0.10 to all other DHCP clients:
+
+default-lease-time 600;
+.br
+max-lease-time 7200;
+.br
+option space openflow;
+.br
+option openflow.controller-vconn code 1 = text;
+.br
+option openflow.pki-uri code 2 = text;
+.br
+class "OpenFlow" {
+.br
+ match if option vendor-class-identifier = "OpenFlow";
+.br
+ vendor-option-space openflow;
+.br
+ option openflow.controller-vconn "tcp:192.168.0.10";
+.br
+ option openflow.pki-uri "http://192.168.0.10/openflow/pki";
+.br
+ option vendor-class-identifier "OpenFlow";
+.br
+}
+.br
+subnet 192.168.0.0 netmask 255.255.255.0 {
+.br
+ pool {
+.br
+ allow members of "OpenFlow";
+.br
+ range 192.168.0.20 192.168.0.30;
+.br
+ }
+.br
+ pool {
+.br
+ deny members of "OpenFlow";
+.br
+ range 192.168.0.1 192.168.0.10;
+.br
+ }
+.br
+}
+.br
+
+.IP "manual configuration"
+To configure in-band control manually, specify the location of the
+controller on the \fBovs\-openflowd\fR command line as the \fIcontroller\fR
+argument. You must also configure the network device for the OpenFlow
+``local port'' to allow \fBovs\-openflowd\fR to connect to that controller.
+The OpenFlow local port is a virtual network port that \fBovs\-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 \fBovs\-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 \fBovs\-openflowd\fR.
+
+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 \fBovs\-openflowd\fR without configuring
+the local port network device, and start the DHCP client afterward.
+.RE
+
+.SH OPTIONS
+.SS "Controller Discovery Options"
+.TP
+\fB--accept-vconn=\fIregex\fR
+When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
+the Controller\fR, above, for more information about controller
+discovery), it validates the controller location obtained via DHCP
+with a POSIX extended regular expression. Only controllers whose
+names match the regular expression will be accepted.
+
+The default regular expression is \fBssl:.*\fR (meaning that only SSL
+controller connections will be accepted) when any of the SSL
+configuration options \fB--private-key\fR, \fB--certificate\fR, or
+\fB--ca-cert\fR is specified. The default is \fB^tcp:.*\fR otherwise
+(meaning that only TCP controller connections will be accepted).
+
+The \fIregex\fR is implicitly anchored at the beginning of the
+controller location string, as if it begins with \fB^\fR.
+
+When controller discovery is not performed, this option has no effect.
+
+.TP
+\fB--no-resolv-conf\fR
+When \fBovs\-openflowd\fR performs controller discovery (see \fBContacting
+the Controller\fR, above, for more information about controller
+discovery), by default it overwrites the system's
+\fB/etc/resolv.conf\fR with domain information and DNS servers
+obtained via DHCP. If the location of the controller is specified
+using a hostname, rather than an IP address, and the network's DNS
+servers ever change, this behavior is essential. But because it also
+interferes with any administrator or process that manages
+\fB/etc/resolv.conf\fR, when this option is specified, \fBovs\-openflowd\fR
+will not modify \fB/etc/resolv.conf\fR.
+
+\fBovs\-openflowd\fR will only modify \fBresolv.conf\fR if the DHCP response
+that it receives specifies one or more DNS servers.
+
+When controller discovery is not performed, this option has no effect.
+
+.SS "Networking Options"
+.TP
+\fB--datapath-id=\fIdpid\fR
+Sets \fIdpid\fR, which must consist of exactly 12 hexadecimal digits,
+as the datapath ID that the switch will use to identify itself to the
+OpenFlow controller.
+
+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).
+
+.TP
+\fB--mgmt-id=\fImgmtid\fR
+Sets \fImgmtid\fR, which must consist of exactly 12 hexadecimal
+digits, as the switch's management ID.
+
+If this option is omitted, the management ID defaults to 0, signaling
+to the controller that management is supported but not configured.
+
+.TP
+\fB--fail=\fR[\fBopen\fR|\fBclosed\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.
+
+If this option is set to \fBopen\fR (the default), \fBovs\-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, \fBovs\-openflowd\fR causes the datapath to act
+like an ordinary MAC-learning switch. \fBovs\-openflowd\fR will continue to
+retry connection to the controller in the background and, when the
+connection succeeds, it discontinues its fail-open behavior.
+
+If this option is set to \fBclosed\fR, then \fBovs\-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 is 15 seconds, and the minimum value is 5 seconds.
+
+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.
+
+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=closed\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 15 seconds.
+
+.TP
+\fB-l\fR, \fB--listen=\fImethod\fR
+Configures the switch to additionally listen for incoming OpenFlow
+connections for switch management with \fBovs\-ofctl\fR. 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.
+
+.RS
+.TP
+\fBpssl:\fR[\fIport\fR][\fB:\fIip\fR]
+Listens for SSL connections on \fIport\fR (default: 6633). The
+\fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
+are mandatory when this form is used.
+By default, \fB\*(PN\fR listens for connections to any local IP
+address, but \fIip\fR may be specified to listen only for connections
+to the given \fIip\fR.
+
+.TP
+\fBptcp:\fR[\fIport\fR][\fB:\fIip\fR]
+Listens for TCP connections on \fIport\fR (default: 6633).
+By default, \fB\*(PN\fR listens for connections to any local IP
+address, but \fIip\fR may be specified to listen only for connections
+to the given \fIip\fR.
+
+.TP
+\fBpunix:\fIfile\fR
+Listens for connections on Unix domain server socket named \fIfile\fR.
+.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.
+
+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 \fBovs\-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.
+
+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.
+
+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 "Remote Command Execution Options"
+
+.TP
+\fB--command-acl=\fR[\fB!\fR]\fIglob\fR[\fB,\fR[\fB!\fR]\fIglob\fR...]
+Configures the commands that remote OpenFlow connections are allowed
+to invoke using (e.g.) \fBovs\-ofctl execute\fR. The argument is a
+comma-separated sequence of shell glob patterns. A glob pattern
+specified without a leading \fB!\fR is a ``whitelist'' that specifies
+a set of commands that are that may be invoked, whereas a pattern that
+does begin with \fB!\fR is a ``blacklist'' that specifies commands
+that may not be invoked. To be permitted, a command name must be
+whitelisted and must not be blacklisted;
+e.g. \fB--command-acl=up*,!upgrade\fR would allow any command whose name
+begins with \fBup\fR except for the command named \fBupgrade\fR.
+Command names that include characters other than upper- and lower-case
+English letters, digits, and the underscore and hyphen characters are
+unconditionally disallowed.
+
+When the whitelist and blacklist permit a command name, \fBovs\-openflowd\fR
+looks for a program with the same name as the command in the commands
+directory (see below). Other directories are not searched.
+
+.TP
+\fB--command-dir=\fIdirectory\fR
+Sets the directory searched for remote command execution to
+\fBdirectory\fR. The default directory is
+\fB@pkgdatadir@/commands\fR.
+
+.SS "Daemon Options"
+.so lib/daemon.man
+
+.SS "Public Key Infrastructure Options"
+
+.TP
+\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
+Specifies a PEM file containing the private key used as the switch's
+identity for SSL connections to the controller.
+
+.TP
+\fB-c\fR, \fB--certificate=\fIcert.pem\fR
+Specifies a PEM file containing a certificate, signed by the
+controller's certificate authority (CA), that certifies the switch's
+private key to identify a trustworthy switch.
+
+.TP
+\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
+Specifies a PEM file containing the CA certificate used to verify that
+the switch is connected to a trustworthy controller.
+
+.TP
+\fB--bootstrap-ca-cert=\fIcacert.pem\fR
+When \fIcacert.pem\fR exists, this option has the same effect as
+\fB-C\fR or \fB--ca-cert\fR. If it does not exist, then \fBovs\-openflowd\fR
+will attempt to obtain the CA certificate from the controller on its
+first SSL connection and save it to the named PEM file. If it is
+successful, it will immediately drop the connection and reconnect, and
+from then on all SSL connections must be authenticated by a
+certificate signed by the CA certificate thus obtained.
+
+\fBThis option exposes the SSL connection to a man-in-the-middle
+attack obtaining the initial CA certificate\fR, but it may be useful
+for bootstrapping.
+
+This option is only useful if the controller sends its CA certificate
+as part of the SSL certificate chain. The SSL protocol does not
+require the controller to send the CA certificate, but
+\fBcontroller\fR(8) can be configured to do so with the
+\fB--peer-ca-cert\fR option.
+
+.SS "Logging Options"
+.so lib/vlog.man
+.SS "Other Options"
+.so lib/common.man
+.so lib/leak-checker.man
+
+.SH "SEE ALSO"
+
+.BR ovs\-appctl (8),
+.BR ovs\-controller (8),
+.BR ovs\-discover (8),
+.BR ovs\-dpctl (8),
+.BR ovs\-ofctl (8),
+.BR ovs\-pki (8),
+.BR ovs\-vswitchd.conf (5)
projects / openvswitch / commitdiff