.TH secchan 8 "May 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]

.SH DESCRIPTION
The \fBsecchan\fR program sets up a secure channel between a local
OpenFlow datapath and a remote controller.  \fBsecchan\fR connects to
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 optional \fIcontroller\fR argument specifies how to connect to
the OpenFlow controller.  It takes one of the following forms:

.TP
\fBssl:\fIhost\fR[\fB:\fIport\fR]
The specified SSL \fIport\fR (default: 976) 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.

.TP
\fBtcp:\fIhost\fR[\fB:\fIport\fR]
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:

.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 \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).

.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 \fBdpctl
addif\fR.  This configuration is often more convenient than
out-of-band control, because it is not necessary to maintain two
independent networks.

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
brought up using
.BR ifconfig (8),
e.g.:
.RS
.IP
ifconfig of0 up
.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:
.RS
.IP
ifconfig of0 192.168.1.1
.RE
.IP
and then invoke \fBsecchan\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 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--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
controller stays down long enough, no packets can pass through the
switch at all.

If this option is set to \fBopen\fR (the default), \fBsecchan\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, \fBsecchan\fR causes the datapath to act
like an ordinary MAC-learning switch.  \fBsecchan\fR will continue to
retry connection to the controller in the background and, when the
connection succeeds, it discontinues its fail-open behavior.  The
secure channel enters the fail-open mode when

If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
set up flows on its own when the controller connection fails.

.TP
\fB--inactivity-probe=\fIsecs\fR
When the secure channel is connected to the controller, the secure
channel 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 secure channel
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
secure channel 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 secure channel will never
expire.  The default is 15 seconds.

Most flows are set up by the OpenFlow controller, not by the secure
channel.  This option affects only the following flows, which the
secure channel sets up itself:

.RS
.IP \(bu
When \fB--fail=open\fR is specified, flows set up when the secure
channel 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=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 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]
Listens for SSL connections on \fIport\fR (default: 976).  The
\fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
are mandatory when this form is used.

.TP
\fBptcp:\fR[\fIport\fR]
Listens for TCP connections on \fIport\fR (default: 975).
.RE

.TP
\fBpunix:\fIfile\fR
Listens for connections on Unix domain server socket named \fIfile\fR.

.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-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
the PID of the running process.  If \fIpidfile\fR is not specified, or
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
run as a background process.

.TP
.BR \-h ", " \-\^\-help
Prints a brief help message to the console.

.TP
\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.  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
Sets the maximum logging verbosity level, equivalent to
\fB--verbose=ANY:ANY:dbg\fR.

.TP
.BR \-V ", " \-\^\-version
Prints version information to the console.

.SH "SEE ALSO"

.BR dpctl (8),
.BR ofp-discover (8),
.BR controller (8),
.BR ofp-pki (8),
.BR vlogconf (8),
.BR switch (8)