.TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"

.SH NAME
switch \- userspace implementation of OpenFlow switch

.SH SYNOPSIS
.B switch
[\fIoptions\fR]
\fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR]...
\fIcontroller\fR

.SH DESCRIPTION
The \fBswitch\fR is a userspace implementation of an OpenFlow switch.
It implements all three parts of the OpenFlow switch specification: a
``flow table'' in which each flow entry is associated with an action
telling the switch how to process the flow; a ``secure channel''
connecting the switch to a remote process (a controller), allowing
commands and packets to be sent between the controller and the switch;
and an OpenFlow protocol implementation.

\fBswitch\fR monitors one or more network device interfaces,
forwarding packets between them according to the entries in the flow
table.  It also maintains a connection to an OpenFlow controller over
a TCP or SSL connection, relaying packets that do not match a flow
table entry to the controller and executing commands sent by the
controller.

For access to network devices, the switch program must normally run as
root.

The mandatory \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.

.SH OPTIONS
.TP
\fB-i\fR, \fB--interfaces=\fR\fInetdev\fR[\fB,\fInetdev\fR]...
Specifies each \fInetdev\fR (e.g., \fBeth0\fR) as a switch port.  The
specified network devices should not have any configured IP addresses.
This option may be given any number of times to specify additional
network devices.

.TP
\fB-d\fR, \fB--datapath-id=\fIdpid\fR
Specifies the OpenFlow switch ID (a 48-bit number that uniquely
identifies a controller) as \fIdpid\fR, which consists of exactly 12
hex digits.  Without this option, \fBswitch\fR picks an ID randomly.

.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, \fBswitch.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-D\fR, \fB--detach\fR
Causes \fBswitch\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\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\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.

.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 BUGS

The userspace switch implementation lags significantly behind the
kernel-based switch, both in implementation quality and performance.
It should only be used when the kernel-based switch cannot be.

General-purpose support for VLAN tag rewriting is precluded by the
Linux kernel AF_PACKET implementation.

.SH "SEE ALSO"

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