-.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:
+.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.
+
+.PP
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
+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: 975) on the given remote
+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.
+.PP
If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
location of the controller automatically (see below).
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.
+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:
.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.:
+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
-.IP
-ifconfig of0 up
+.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
.RE
.IP
-As a result, when both \fB--fail=open\fR and in-band control are not
-in use, this option has no effect.
+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
.RS
.TP
\fBpssl:\fR[\fIport\fR]
-Listens for SSL connections on \fIport\fR (default: 976). The
+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: 975).
+Listens for TCP connections on \fIport\fR (default: 6633).
.TP
\fBpunix:\fIfile\fR
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--netflow=\fIhost\fB:\fIport\fR
+When flows end on the switch, send NetFlow v5 messages to
+\fIhost\fR on UDP \fIport\fR.
+
.TP
\fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
Specifies a PEM file containing the private key used as the switch's
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.
+\fB@RUNDIR@\fR.
.TP
\fB-f\fR, \fB--force\fR
.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.
+@VLOG_OPTIONS@
.TP
.BR \-V ", " \-\^\-version
.BR ofp-discover (8),
.BR controller (8),
.BR ofp-pki (8),
-.BR vlogconf (8),
-.BR switch (8)
+.BR udatapath (8),
+.BR vlogconf (8)
git://git.onelab.eu / sliver-openvswitch.git / blobdiff