465 lines
17 KiB
Plaintext
465 lines
17 KiB
Plaintext
.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] \fIdatapath\fR [\fIcontroller\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 \fIdatapath\fR argument argument specifies the local datapath
|
|
to relay. It takes one of the following forms:
|
|
|
|
.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
|
|
\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.
|
|
|
|
.TP
|
|
\fBtcp:\fIhost\fR[\fB:\fIport\fR]
|
|
The specified TCP \fIport\fR (default: 6633) 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, 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
|
|
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.
|
|
|
|
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 "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 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
|
|
.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
|
|
the local port network device, 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: 6633). 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: 6633).
|
|
|
|
.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--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.) \fBdpctl 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, \fBsecchan\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.
|
|
|
|
.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 \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
|
|
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.
|
|
|
|
@VLOG_OPTIONS@
|
|
|
|
.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)
|