.SH SYNOPSIS
.B secchan
-[\fIoptions\fR] \fBnl:\fIdp_idx\fR \fIremote\fR
+[\fIoptions\fR] \fBnl:\fIdp_idx\fR [\fIremote\fR]
.SH DESCRIPTION
The \fBsecchan\fR program sets up a secure channel between a local
datapath that has been created with
.BR dpctl (8).
-The mandatory \fIcontroller\fR argument specifies how to connect to
+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:
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
+With in-band control, the location of the controller can be configured
+manually or discovered automatically:
+
+.RS
+.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"
+Configuring in-band control manually 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
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.
+.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-p\fR, \fB--private-key=\fIprivkey.pem\fR
Specifies a PEM file containing the private key used as the switch's
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