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: 6633).  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: 6633).
  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: 6633) 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: 6633) 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=\fIswitch-cacert.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 \fB--peer-ca-cert=\fIcontroller-cacert.pem\fR
  77 Specifies a PEM file that contains one or more additional certificates
  78 to send to switches.  \fIcontroller-cacert.pem\fR should be the CA
  79 certificate used to sign the controller's own certificate (the
  80 certificate specified on \fB-c\fR or \fB--certificate\fR).
  81
  82 This option is not useful in normal operation, because the switch must
  83 already have the controller CA certificate for it to have any
  84 confidence in the controller's identity.  However, this option allows
  85 a newly installed switch to obtain the controller CA certificate on
  86 first boot using, e.g., the \fB--bootstrap-ca-cert\fR option to
  87 \fBsecchan\fR(8).
  88
  89 .TP
  90 .BR \-n ", " \-\^\-noflow
  91 By default, the controller sets up a flow in each OpenFlow switch
  92 whenever it receives a packet whose destination is known due through
  93 MAC learning.  This option disables flow setup, so that every packet
  94 in the network passes through the controller.
  95
  96 This option is most useful for debugging.  It reduces switching
  97 performance, so it should not be used in production.
  98
  99 .TP
 100 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 101 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 102 controller will remain in the switch's flow table without any matching
 103 packets being seen.  If \fBpermanent\fR is specified, which is not
 104 recommended, flows will never expire.  The default is 60 seconds.
 105
 106 This option affects only flows set up by the OpenFlow controller.  In
 107 some configurations, the OpenFlow secure channel can set up some flows
 108 on its own.  To set the idle time for those flows, pass
 109 \fB--max-idle\fR to \fBsecchan\fR(8).
 110
 111 This option has no effect when \fB-n\fR (or \fB--noflow\fR) is in use
 112 (because the controller does not set up flows in that case).
 113
 114 .TP
 115 .BR \-H ", " \-\^\-hub
 116 By default, the controller acts as an L2 MAC-learning switch.  This
 117 option changes its behavior to that of a hub that floods packets on
 118 all but the incoming port.
 119
 120 If \fB-H\fR (or \fB--hub\fR) and \fB-n\fR (or \fB--noflow\fR) are used
 121 together, then the cumulative effect is that every packet passes
 122 through the controller and every packet is flooded.
 123
 124 This option is most useful for debugging.  It reduces switching
 125 performance, so it should not be used in production.
 126
 127 .TP
 128 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 129 Causes a file (by default, \fBcontroller.pid\fR) to be created indicating
 130 the PID of the running process.  If \fIpidfile\fR is not specified, or
 131 if it does not begin with \fB/\fR, then it is created in
 132 \fB@RUNDIR@\fR.
 133
 134 .TP
 135 \fB-f\fR, \fB--force\fR
 136 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
 137 specified pidfile already exists and is locked by a running process,
 138 \fBcontroller\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
 139 to cause it to instead overwrite the pidfile.
 140
 141 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 142 effect.
 143
 144 .TP
 145 \fB-D\fR, \fB--detach\fR
 146 Causes \fBcontroller\fR to detach itself from the foreground session and
 147 run as a background process.
 148
 149 .TP
 150 .BR \-h ", " \-\^\-help
 151 Prints a brief help message to the console.
 152
 153 @VLOG_OPTIONS@
 154
 155 .TP
 156 .BR \-V ", " \-\^\-version
 157 Prints version information to the console.
 158
 159 .SH EXAMPLES
 160
 161 .TP
 162 To connect directly to local datapath 0 over netlink (Linux only):
 163
 164 .B % controller nl:0
 165
 166 .TP
 167 To bind locally to port 6633 (the default) and wait for incoming connections from OpenFlow switches:
 168
 169 .B % controller ptcp:
 170
 171 .SH "SEE ALSO"
 172
 173 .BR dpctl (8),
 174 .BR secchan (8),
 175 .BR udatapath (8),
 176 .BR vlogconf (8)