controller/controller.8.in

   1 .TH controller 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 controller \- simple OpenFlow controller reference implementation
   5
   6 .SH SYNOPSIS
   7 .B controller
   8 [\fIoptions\fR] \fImethod\fR \fB[\fImethod\fR]\&...
   9
  10 .SH DESCRIPTION
  11 A sample OpenFlow controller which functions as an L2 MAC-learning
  12 switch or hub.  \fBcontroller\fR can manage a remote datapath through
  13 a secure channel (see \fBsecchan(8)\fR).  It can also connect directly
  14 to a local datapath via Netlink.
  15
  16 \fBcontroller\fR controls one or more OpenFlow switches, specified as
  17 one or more of the following OpenFlow connection methods:
  18
  19 .TP
  20 \fBpssl:\fR[\fIport\fR]
  21 Listens for SSL connections from remote OpenFlow switches on
  22 \fIport\fR (default: 976).  The \fB--private-key\fR,
  23 \fB--certificate\fR, and \fB--ca-cert\fR options are mandatory when
  24 this form is used.
  25
  26 .TP
  27 \fBptcp:\fR[\fIport\fR]
  28 Listens for TCP connections from remote OpenFlow switches on
  29 \fIport\fR (default: 975).
  30
  31 .TP
  32 \fBpunix:\fIfile\fR
  33 Listens for connections from OpenFlow switches on the Unix domain
  34 server socket named \fIfile\fR.
  35
  36 .TP
  37 \fBnl:\fIdp_idx\fR
  38 The local Netlink datapath numbered \fIdp_idx\fR, as configured with
  39 .BR dpctl (8).
  40 This form requires that the local host has the OpenFlow kernel
  41 module for Linux loaded.
  42
  43 .TP
  44 \fBssl:\fIhost\fR[\fB:\fIport\fR]
  45 The specified SSL \fIport\fR (default: 976) on the given remote
  46 \fIhost\fR.  The \fB--private-key\fR, \fB--certificate\fR, and
  47 \fB--ca-cert\fR options are mandatory when this form is used.
  48
  49 .TP
  50 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
  51 The specified TCP \fIport\fR (default: 975) on the given remote
  52 \fIhost\fR.
  53
  54 .TP
  55 \fBunix:\fIfile\fR
  56 The Unix domain server socket named \fIfile\fR.
  57
  58 .SH OPTIONS
  59 .TP
  60 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
  61 Specifies a PEM file containing the private key used as the switch's
  62 identity for SSL connections to the controller.
  63
  64 .TP
  65 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
  66 Specifies a PEM file containing a certificate, signed by the
  67 controller's certificate authority (CA), that certifies the switch's
  68 private key to identify a trustworthy switch.
  69
  70 .TP
  71 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
  72 Specifies a PEM file containing the CA certificate used to verify that
  73 the switch is connected to a trustworthy controller.
  74
  75 .TP
  76 .BR \-n ", " \-\^\-noflow
  77 By default, the controller sets up a flow in each OpenFlow switch
  78 whenever it receives a packet whose destination is known due through
  79 MAC learning.  This option disables flow setup, so that every packet
  80 in the network passes through the controller.
  81
  82 This option is most useful for debugging.  It reduces switching
  83 performance, so it should not be used in production.
  84
  85 .TP
  86 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
  87 Sets \fIsecs\fR as the number of seconds that a flow set up by the
  88 controller will remain in the switch's flow table without any matching
  89 packets being seen.  If \fBpermanent\fR is specified, which is not
  90 recommended, flows will never expire.  The default is 60 seconds.
  91
  92 This option affects only flows set up by the OpenFlow controller.  In
  93 some configurations, the OpenFlow secure channel can set up some flows
  94 on its own.  To set the idle time for those flows, pass
  95 \fB--max-idle\fR to \fBsecchan\fR(8).
  96
  97 This option has no effect when \fB-n\fR (or \fB--noflow\fR) is in use
  98 (because the controller does not set up flows in that case).
  99
 100 .TP
 101 .BR \-H ", " \-\^\-hub
 102 By default, the controller acts as an L2 MAC-learning switch.  This
 103 option changes its behavior to that of a hub that floods packets on
 104 all but the incoming port.
 105
 106 If \fB-H\fR (or \fB--hub\fR) and \fB-n\fR (or \fB--noflow\fR) are used
 107 together, then the cumulative effect is that every packet passes
 108 through the controller and every packet is flooded.
 109
 110 This option is most useful for debugging.  It reduces switching
 111 performance, so it should not be used in production.
 112
 113 .TP
 114 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 115 Causes a file (by default, \fBcontroller.pid\fR) to be created indicating
 116 the PID of the running process.  If \fIpidfile\fR is not specified, or
 117 if it does not begin with \fB/\fR, then it is created in
 118 \fB@rundir@\fR.
 119
 120 .TP
 121 \fB-f\fR, \fB--force\fR
 122 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
 123 specified pidfile already exists and is locked by a running process,
 124 \fBcontroller\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
 125 to cause it to instead overwrite the pidfile.
 126
 127 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 128 effect.
 129
 130 .TP
 131 \fB-D\fR, \fB--detach\fR
 132 Causes \fBcontroller\fR to detach itself from the foreground session and
 133 run as a background process.
 134
 135 .TP
 136 .BR \-h ", " \-\^\-help
 137 Prints a brief help message to the console.
 138
 139 .TP
 140 \fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 141 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 142 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 143 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 144 special name \fBANY\fR to set the logging levels for all modules.  The
 145 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 146 for logging to the system log or to the console, respectively, or
 147 \fBANY\fR to set the logging levels for both facilities.  If it is
 148 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 149 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 150 the minimum severity of a message for it to be logged.  If it is
 151 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 152
 153 .TP
 154 \fB-v\fR, \fB--verbose\fR
 155 Sets the maximum logging verbosity level, equivalent to
 156 \fB--verbose=ANY:ANY:dbg\fR.
 157
 158 .TP
 159 .BR \-V ", " \-\^\-version
 160 Prints version information to the console.
 161
 162 .SH EXAMPLES
 163
 164 .TP
 165 To connect directly to local datapath 0 over netlink (Linux only):
 166
 167 .B % controller nl:0
 168
 169 .TP
 170 To bind locally to port 975 (the default) and wait for incoming connections from OpenFlow switches:
 171
 172 .B % controller ptcp:
 173
 174 .SH "SEE ALSO"
 175
 176 .BR dpctl (8),
 177 .BR switch (8),
 178 .BR secchan (8),
 179 .BR vlogconf (8)