-.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"
+.TH secchan 8 "October 2008" "OpenFlow" "OpenFlow Manual"
.SH NAME
secchan \- secure channel connecting an OpenFlow datapath to a controller
.SH SYNOPSIS
.B secchan
-[\fIoptions\fR] \fBnl:\fIdp_idx\fR \fIremote\fR
+[\fIoptions\fR] \fIdatapath\fR [\fIcontroller\fR]
.SH DESCRIPTION
The \fBsecchan\fR program sets up a secure channel between a local
the local datapath over Netlink and to the controller over TCP or SSL,
and then forwards OpenFlow messages from one endpoint to the other.
-The mandatory \fBnl:\fIdp_idx\fR argument specifies the local datapath
-to relay. Within this argument, \fIdp_idx\fR is the number of a
-datapath that has been created with
-.BR dpctl (8).
+The mandatory \fIdatapath\fR argument argument specifies the local datapath
+to relay. It takes one of the following forms:
-The mandatory \fIcontroller\fR argument specifies how to connect to
+.TP
+\fBnl:\fIdp_idx\fR
+Attach to the local kernel-based datapath over the Netlink protocol.
+The \fIdp_idx\fR argument is the number of a datapath created with
+\fBdpctl\fR(8).
+
+.TP
+\fBunix:\fIfile\fR
+Attach to the userspace datapath implemented by \fBudatapath\fR(8).
+The \fIfile\fR argument must the same one specified on the
+\fBudatapath\fR command line.
+
+The optional \fIcontroller\fR argument specifies how to connect to
the OpenFlow controller. It takes one of the following forms:
.TP
The specified TCP \fIport\fR (default: 975) on the given remote
\fIhost\fR.
+.TP
+\fBunix:\fIfile\fR
+The Unix domain server socket named \fIfile\fR.
+
+If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
+location of the controller automatically (see below).
+
.SH "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:
any of the network devices added to the datapath with \fBdpctl
addif\fR in its communication with the controller.
-To use \fBsecchan\fR in a network with out-of-band control, the
-control network must be configured for use by \fBsecchan\fR at the
-time it is started. No additional setup is required. In particular,
-the \fBof\fIn\fR device should not be up or configured with an IP
-address (see below).
+To use \fBsecchan\fR in a network with out-of-band control, specify
+\fB--out-of-band\fR on the \fBsecchan\fR command line. The control
+network must be configured separately, before or after \fBsecchan\fR
+is started.
.IP in-band
In this configuration, a single network is used for OpenFlow traffic
out-of-band control, because it is not necessary to maintain two
independent networks.
-Using \fBsecchan\fR in a network with in-band control requires
-additional setup before starting \fBsecchan\fR. At a minimum, the
-special OpenFlow network device \fBof\fIn\fR, where \fIn\fR is same as
-the \fIdp_idx\fR specified on the \fBsecchan\fR command line, must be
-brought up using
-.BR ifconfig (8),
-e.g.:
+In-band control is the default for \fBsecchan\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
-ifconfig of0 up
+.IP "controller discovery"
+To make \fBsecchan\fR discover the location of the controller
+automatically, do not specify the location of the controller on the
+\fBsecchan\fR command line.
+
+In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
+class identifier \fBOpenFlow\fR across the network devices added to
+the datapath with \fBdpctl addif\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 \fBsecchan\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; \fBsecchan\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 \fBsecchan\fR command line as the \fIcontroller\fR
+argument. You must also configure the network device for the OpenFlow
+``local port'' to allow \fBsecchan\fR to connect to that controller.
+The OpenFlow local port is a virtual network port that \fBsecchan\fR
+bridges to the physical switch ports. Its network device name depends
+on the \fIdatapath\fR specified on the \fBsecchan\fR command line:
+
+.RS
+.TP
+\fBnl:\fIdp_idx\fR
+The local port network device for \fBnl:\fIdp_idx\fR is always named
+\fBof\fIdp_idx\fR, i.e. the device for \fBnl:0\fR is \fBof0\fR.
+
+.TP
+\fBunix:\fIfile\fR
+The local port network device name may be specified on the
+\fBudatapath\fR command line, using the \fB--local-port\fR option. It
+is often \fBtap0\fR.
.RE
+
.IP
-Before \fBsecchan\fR starts, the \fBof\fIn\fR device cannot send or
-receive any packets, 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:
+Before \fBsecchan\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:
.RS
.IP
ifconfig of0 192.168.1.1
e.g. it obtains its IP address dynamically via DHCP, the DHCP client
will not be able to contact the DHCP server until the secure channel
has started up. Thus, start \fBsecchan\fR without configuring
-\fBof\fIn\fR further, and start the DHCP client afterward.
+the local port network device, and start the DHCP client afterward.
+.RE
.SH OPTIONS
.TP
-\fB-f\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
+\fB--accept-vconn=\fIregex\fR
+When \fBsecchan\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.*\fR otherwise
+(meaning that any controller 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 \fBsecchan\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, \fBsecchan\fR
+will not modify \fB/etc/resolv.conf\fR.
+
+\fBsecchan\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.
+
+.TP
+\fB-F\fR, \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
As a result, when both \fB--fail=open\fR and in-band control are not
in use, 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 \fBdpctl\fR. The \fImethod\fR
-must be given as one of the following passive OpenFlow connection
-methods:
+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
.TP
\fBptcp:\fR[\fIport\fR]
Listens for TCP connections on \fIport\fR (default: 975).
+
+.TP
+\fBpunix:\fIfile\fR
+Listens for connections on Unix domain server socket named \fIfile\fR.
.RE
+.TP
+\fB-m\fR, \fB--monitor=\fImethod\fR
+Configures the switch to additionally listen for incoming OpenFlow
+connections for switch monitoring with \fBdpctl\fR's \fBmonitor\fR
+command. The \fImethod\fR must be given as one of the passive
+OpenFlow connection methods listed above as acceptable for
+\fB--listen\fR.
+
+When \fBdpctl monitor\fR makes a monitoring connection, \fBsecchan\fR
+sends it a copy of every OpenFlow message sent to or received from the
+kernel in the normal course of its operations. It does not send a
+copy of any messages sent to or from the OpenFlow connection to the
+controller. Most of these messages will be seen anyhow, however,
+because \fBsecchan\fR mainly acts as a relay between the controller
+and the kernel. \fBsecchan\fR also does not send a copy of any
+messages sent to or from the OpenFlow connection to the controller.
+Such messages will typically \fBnot\fR be seen, because \fBsecchan\fR
+maintains a separate connection to the kernel for each management
+connection.
+
+Messages are copied to the monitoring connections on a best-effort
+basis. In particular, if the socket buffer of the monitoring
+connection fills up, some messages will be lost.
+
+.TP
+\fB--in-band\fR, \fB--out-of-band\fR
+Configures \fBsecchan\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--stp\fR, \fB--no-stp\fR
+Enable or disable implementation of IEEE 802.1D Spanning Tree Protocol
+at the switch. The default is \fB--no-stp\fR in this distribution,
+because bugs in the STP implementation are still being worked out.
+The default will change to \fB--stp\fR at some point in the future.
+
.TP
\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
Specifies a PEM file containing the private key used as the switch's
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 \fBsecchan\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.
+
.TP
\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
if it does not begin with \fB/\fR, then it is created in
\fB@rundir@\fR.
+.TP
+\fB-f\fR, \fB--force\fR
+By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
+specified pidfile already exists and is locked by a running process,
+\fBsecchan\fR refuses to start. Specify \fB-f\fR or \fB--force\fR
+to cause it to instead overwrite the pidfile.
+
+When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
+effect.
+
.TP
\fB-D\fR, \fB--detach\fR
Causes \fBsecchan\fR to detach itself from the foreground session and
Prints a brief help message to the console.
.TP
-\fB-v\fR \fImodule\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\fB:\fIlevel\fR
+\fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
Sets the logging level for \fImodule\fR in \fIfacility\fR to
\fIlevel\fR. The \fImodule\fR may be any valid module name (as
displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
special name \fBANY\fR to set the logging levels for all modules. The
\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities. The
-\fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
-\fBdbg\fR, designating the minimum severity of a message for it to be
-logged.
+\fBANY\fR to set the logging levels for both facilities. If it is
+omitted, \fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must
+be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
+the minimum severity of a message for it to be logged. If it is
+omitted, \fIlevel\fR defaults to \fBdbg\fR.
.TP
\fB-v\fR, \fB--verbose\fR
.SH "SEE ALSO"
.BR dpctl (8),
+.BR ofp-discover (8),
.BR controller (8),
.BR ofp-pki (8),
.BR vlogconf (8),
git://git.onelab.eu / sliver-openvswitch.git / blobdiff