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

.SH NAME
udatapath \- userspace implementation of datapath for OpenFlow switch

.SH SYNOPSIS
.B udatapath
[\fIoptions\fR]
\fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR].\|.\|.
\fImethod\fR [\fImethod\fR].\|.\|.

.SH DESCRIPTION
The \fBudatapath\fR is a userspace implementation of an OpenFlow
datapath.  It monitors one or more network device interfaces,
forwarding packets between them according to the entries in the flow
table that it maintains.  When it is used with \fBsecchan\fR(8), to
connect the datapath to an OpenFlow controller, the combination is an
OpenFlow switch.

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

The mandatory \fImethod\fR argument specifies how \fBsecchan\fR(8)
communicates with \fBudatapath\fR, as a passive OpenFlow connection
method.  Ordinarily \fImethod\fR takes the following form:

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

.PP
The following connection methods are also supported, but their use
would be unusual because \fBudatapath\fR and \fBsecchan\fR should run
on the same machine:

.TP
\fBpssl:\fR[\fIport\fR]
Listens for SSL connections \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.  (\fBofp\-pki\fR(8) does not set
up a suitable PKI for use with this option.)

.TP
\fBptcp:\fR[\fIport\fR]
Listens for TCP connections from remote OpenFlow switches on
\fIport\fR (default: 975).

.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-L\fR, \fB--local-port=\fInetdev\fR
Specifies the network device to use as the userspace datapath's
``local port,'' which is a network device that \fBsecchan\fR(8)
bridges to the physical switch ports for use in in-band control.  When
this option is not specified, the default is \fBtap:\fR, which causes
a new TAP virtual network device to be allocated with a default name
assigned by the kernel.  To do the same, but assign a specific name
\fBname\fR to the TAP network device, specify the option as
\fB--local-port=tap:\fIname\fR.

Either way, the existence of TAP devices created by \fBudatapath\fR is
temporary: they are destroyed when \fBudatapath\fR exits.  If this is
undesirable, you may use \fBtunctl\fR(8) to create a persistent TAP
network device and then pass it to \fBudatapath\fR, like so:

.RS
.IP 1.
Create a persistent TAP network device: \fBtunctl -t mytap\fR.  (The
\fBtunctl\fR(8) utility is part of User Mode Linux.  It is not
included with the OpenFlow reference implementation.)
.IP 2.
Invoke \fBudatapath\fR(8) using \fBmytap\fR, e.g. \fBudatapath
--local-port=mytap\fR .\|.\|.  (Note the lack of \fBtap:\fR prefix on
the \fB--local-port\fR argument.)
.IP 3.
Invoke \fBsecchan\fR(8), etc., and use the switch as desired.
.IP 4.
When \fBsecchan\fR and \fBudatapath\fR have terminated and the TAP
network device is no longer needed, you may destroy it with: \fBtunctl
-d mytap\fR
.RE

.IP
It does not ordinarily make sense to specify the name of a physical
network device on \fB-L\fR or \fB--local-port\fR.

.TP
\fB--no-local-port\fR
Do not provide a local port as part of the datapath.  When this option
is used, the switch will not support in-band control.

.TP
\fB-d\fR, \fB--datapath-id=\fIdpid\fR
Specifies the OpenFlow datapath ID (a 48-bit number that uniquely
identifies a controller) as \fIdpid\fR, which consists of exactly 12
hex digits.  Without this option, \fBudatapath\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 datapath's
identity for SSL connections to \fBsecchan\fR(8).

.TP
\fB-c\fR, \fB--certificate=\fIcert.pem\fR
Specifies a PEM file containing a certificate, signed by the
datapath's certificate authority (CA), that certifies the datapath's
private key to identify a trustworthy datapath.

.TP
\fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
Specifies a PEM file containing the CA certificate used to verify that
the datapath is connected to a trustworthy secure channel.

.TP
\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fBudatapath.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,
\fBudatapath\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 \fBudatapath\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\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 BUGS
The userspace datapath's performance lags significantly behind that of
the kernel-based switch.  It should only be used when the kernel-based
switch cannot be.

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

.SH "SEE ALSO"

.BR secchan (8),
.BR dpctl (8),
.BR controller (8),
.BR vlogconf (8).