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

.SH NAME
controller \- simple OpenFlow controller reference implementation

.SH SYNOPSIS
.B controller
[\fIoptions\fR] \fImethod\fR \fB[\fImethod\fR]\&...

.SH DESCRIPTION
A sample OpenFlow controller which functions as an L2 MAC-learning
switch or hub.  \fBcontroller\fR can manage a remote datapath through
a secure channel (see \fBsecchan(8)\fR).  It can also connect directly
to a local datapath via Netlink.

\fBcontroller\fR controls one or more OpenFlow switches, specified as
one or more of the following OpenFlow connection methods:

.TP
\fBpssl:\fR[\fIport\fR]
Listens for SSL connections from remote OpenFlow switches 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 from remote OpenFlow switches on
\fIport\fR (default: 975).

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

.TP
\fBnl:\fIdp_idx\fR
The local Netlink datapath numbered \fIdp_idx\fR, as configured with
.BR dpctl (8).
This form requires that the local host has the OpenFlow kernel
module for Linux loaded.

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

.SH OPTIONS
.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
.BR \-n ", " \-\^\-noflow
By default, the controller sets up a flow in each OpenFlow switch
whenever it receives a packet whose destination is known due through
MAC learning.  This option disables flow setup, so that every packet
in the network passes through the controller.

This option is most useful for debugging.  It reduces switching
performance, so it should not be used in production.

.TP
\fB--max-idle=\fIsecs\fR|\fBpermanent\fR
Sets \fIsecs\fR as the number of seconds that a flow set up by the
controller will remain in the switch's flow table without any matching
packets being seen.  If \fBpermanent\fR is specified, which is not
recommended, flows will never expire.  The default is 60 seconds.

This option affects only flows set up by the OpenFlow controller.  In
some configurations, the OpenFlow secure channel can set up some flows
on its own.  To set the idle time for those flows, pass
\fB--max-idle\fR to \fBsecchan\fR(8).

This option has no effect when \fB-n\fR (or \fB--noflow\fR) is in use
(because the controller does not set up flows in that case).

.TP
.BR \-H ", " \-\^\-hub
By default, the controller acts as an L2 MAC-learning switch.  This
option changes its behavior to that of a hub that floods packets on
all but the incoming port.

If \fB-H\fR (or \fB--hub\fR) and \fB-n\fR (or \fB--noflow\fR) are used
together, then the cumulative effect is that every packet passes
through the controller and every packet is flooded.

This option is most useful for debugging.  It reduces switching
performance, so it should not be used in production.

.TP
\fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
Causes a file (by default, \fBcontroller.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,
\fBcontroller\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 \fBcontroller\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 EXAMPLES

.TP
To connect directly to local datapath 0 over netlink (Linux only):

.B % controller nl:0

.TP
To bind locally to port 975 (the default) and wait for incoming connections from OpenFlow switches:

.B % controller ptcp:

.SH "SEE ALSO"

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