secchan/secchan.8.in

   1 .TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 secchan \- secure channel connecting an OpenFlow datapath to a controller
   5
   6 .SH SYNOPSIS
   7 .B secchan
   8 [\fIoptions\fR] \fBnl:\fIdp_idx\fR [\fIremote\fR]
   9
  10 .SH DESCRIPTION
  11 The \fBsecchan\fR program sets up a secure channel between a local
  12 OpenFlow datapath and a remote controller.  \fBsecchan\fR connects to
  13 the local datapath over Netlink and to the controller over TCP or SSL,
  14 and then forwards OpenFlow messages from one endpoint to the other.
  15
  16 The mandatory \fBnl:\fIdp_idx\fR argument specifies the local datapath
  17 to relay.  Within this argument, \fIdp_idx\fR is the number of a
  18 datapath that has been created with
  19 .BR dpctl (8).
  20
  21 The optional \fIcontroller\fR argument specifies how to connect to
  22 the OpenFlow controller.  It takes one of the following forms:
  23
  24 .TP
  25 \fBssl:\fIhost\fR[\fB:\fIport\fR]
  26 The specified SSL \fIport\fR (default: 976) on the given remote
  27 \fIhost\fR.  The \fB--private-key\fR, \fB--certificate\fR, and
  28 \fB--ca-cert\fR options are mandatory when this form is used.
  29
  30 .TP
  31 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
  32 The specified TCP \fIport\fR (default: 975) on the given remote
  33 \fIhost\fR.
  34
  35 If \fIcontroller\fR is omitted, \fBsecchan\fR attempts to discover the
  36 location of the controller automatically (see below).
  37
  38 .SH "CONTACTING THE CONTROLLER"
  39 The OpenFlow switch must be able to contact the OpenFlow controller
  40 over the network.  It can do so in one of two ways:
  41
  42 .IP out-of-band
  43 In this configuration, OpenFlow traffic uses a network separate from
  44 the data traffic that it controls, that is, the switch does not use
  45 any of the network devices added to the datapath with \fBdpctl
  46 addif\fR in its communication with the controller.
  47
  48 To use \fBsecchan\fR in a network with out-of-band control, the
  49 control network must be configured for use by \fBsecchan\fR at the
  50 time it is started.  No additional setup is required.  In particular,
  51 the \fBof\fIn\fR device should not be up or configured with an IP
  52 address (see below).
  53
  54 .IP in-band
  55 In this configuration, a single network is used for OpenFlow traffic
  56 and other data traffic, that is, the switch contacts the controller
  57 over one of the network devices added to the datapath with \fBdpctl
  58 addif\fR.  This configuration is often more convenient than
  59 out-of-band control, because it is not necessary to maintain two
  60 independent networks.
  61
  62 With in-band control, the location of the controller can be configured
  63 manually or discovered automatically:
  64
  65 .RS
  66 .IP "controller discovery"
  67 To make \fBsecchan\fR discover the location of the controller
  68 automatically, do not specify the location of the controller on the
  69 \fBsecchan\fR command line.
  70
  71 In this mode, \fBsecchan\fR will broadcast a DHCP request with vendor
  72 class identifier \fBOpenFlow\fR across the network devices added to
  73 the datapath with \fBdpctl addif\fR.  It will accept any valid DHCP
  74 reply that has the same vendor class identifier and includes a
  75 vendor-specific option with code 1 whose contents are a string
  76 specifying the location of the controller in the same format used on
  77 the \fBsecchan\fR command line (e.g. \fBssl:192.168.0.1\fR).
  78
  79 The following ISC DHCP server configuration file assigns the IP
  80 address range 192.168.0.20 through 192.168.0.30 to OpenFlow switches
  81 that follow the switch protocol and addresses 192.168.0.1 through
  82 192.168.0.10 to all other DHCP clients:
  83
  84 default-lease-time 600;
  85 .br
  86 max-lease-time 7200;
  87 .br
  88 option space openflow;
  89 .br
  90 option openflow.controller-vconn code 1 = text;
  91 .br
  92 class "OpenFlow" {
  93 .br
  94   match if option vendor-class-identifier = "OpenFlow";
  95 .br
  96   vendor-option-space openflow;
  97 .br
  98   option openflow.controller-vconn "tcp:192.168.0.10";
  99 .br
 100   option vendor-class-identifier "OpenFlow";
 101 .br
 102 }
 103 .br
 104 subnet 192.168.0.0 netmask 255.255.255.0 {
 105 .br
 106     pool {
 107 .br
 108         allow members of "OpenFlow";
 109 .br
 110         range 192.168.0.20 192.168.0.30;
 111 .br
 112     }
 113 .br
 114     pool {
 115 .br
 116         deny members of "OpenFlow";
 117 .br
 118         range 192.168.0.1 192.168.0.10;
 119 .br
 120     }
 121 .br
 122 }
 123 .br
 124
 125 .IP "manual configuration"
 126 Configuring in-band control manually requires
 127 additional setup before starting \fBsecchan\fR.  At a minimum, the
 128 special OpenFlow network device \fBof\fIn\fR, where \fIn\fR is same as
 129 the \fIdp_idx\fR specified on the \fBsecchan\fR command line, must be
 130 brought up using
 131 .BR ifconfig (8),
 132 e.g.:
 133 .RS
 134 .IP
 135 ifconfig of0 up
 136 .RE
 137 .IP
 138 Before \fBsecchan\fR starts, the \fBof\fIn\fR device cannot send or
 139 receive any packets, so the next step depends on whether connectivity
 140 is required to configure the device's IP address.  If the switch has a
 141 static IP address, you may configure its IP address now with a command
 142 such as:
 143 .RS
 144 .IP
 145 ifconfig of0 192.168.1.1
 146 .RE
 147 .IP
 148 and then invoke \fBsecchan\fR.
 149
 150 On the other hand, if the switch does not have a static IP address,
 151 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
 152 will not be able to contact the DHCP server until the secure channel
 153 has started up.  Thus, start \fBsecchan\fR without configuring
 154 \fBof\fIn\fR further, and start the DHCP client afterward.
 155 .RE
 156
 157 .SH OPTIONS
 158 .TP
 159 \fB--accept-vconn=\fIregex\fR
 160 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
 161 THE CONTROLLER\fR, above, for more information about controller
 162 discovery), it validates the controller location obtained via DHCP
 163 with a regular expression.  Only controllers whose names match the
 164 regular expression will be accepted.
 165
 166 The default regular expression is \fBssl:.*\fR (meaning that only SSL
 167 controller connections will be accepted) when any of the SSL
 168 configuration options \fB--private-key\fR, \fB--certificate\fR, or
 169 \fB--ca-cert\fR is specified.  The default is \fB.*\fR otherwise
 170 (meaning that any controller will be accepted).
 171
 172 The \fIregex\fR is implicitly anchored at the beginning of the
 173 controller location string, as if it begins with \fB^\fR.
 174
 175 When controller discovery is not performed, this option has no effect.
 176
 177 .TP
 178 \fB-f\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
 179 The controller is, ordinarily, responsible for setting up all flows on
 180 the OpenFlow switch.  Thus, if the connection to the controller fails,
 181 no new network connections can be set up.  If the connection to the
 182 controller stays down long enough, no packets can pass through the
 183 switch at all.
 184
 185 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
 186 take over responsibility for setting up flows in the local datapath
 187 when no message has been received from the controller for three times
 188 the inactivity probe interval (see below), or 45 seconds by default.
 189 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
 190 like an ordinary MAC-learning switch.  \fBsecchan\fR will continue to
 191 retry connection to the controller in the background and, when the
 192 connection succeeds, it discontinues its fail-open behavior.  The
 193 secure channel enters the fail-open mode when
 194
 195 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
 196 set up flows on its own when the controller connection fails.
 197
 198 .TP
 199 \fB--inactivity-probe=\fIsecs\fR
 200 When the secure channel is connected to the controller, the secure
 201 channel waits for a message to be received from the controller for
 202 \fIsecs\fR seconds before it sends a inactivity probe to the
 203 controller.  After sending the inactivity probe, if no response is
 204 received for an additional \fIsecs\fR seconds, the secure channel
 205 assumes that the connection has been broken and attempts to reconnect.
 206 The default is 15 seconds, and the minimum value is 5 seconds.
 207
 208 When fail-open mode is configured, changing the inactivity probe
 209 interval also changes the interval before entering fail-open mode (see
 210 above).
 211
 212 .TP
 213 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 214 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 215 secure channel will remain in the switch's flow table without any
 216 matching packets being seen.  If \fBpermanent\fR is specified, which
 217 is not recommended, flows set up by the secure channel will never
 218 expire.  The default is 15 seconds.
 219
 220 Most flows are set up by the OpenFlow controller, not by the secure
 221 channel.  This option affects only the following flows, which the
 222 secure channel sets up itself:
 223
 224 .RS
 225 .IP \(bu
 226 When \fB--fail=open\fR is specified, flows set up when the secure
 227 channel has not been able to contact the controller for the configured
 228 fail-open delay.
 229
 230 .IP \(bu
 231 When in-band control is in use, flows set up to bootstrap contacting
 232 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
 233 more information about in-band control).
 234 .RE
 235
 236 .IP
 237 As a result, when both \fB--fail=open\fR and in-band control are not
 238 in use, this option has no effect.
 239
 240 .TP
 241 \fB--max-backoff=\fIsecs\fR
 242 Sets the maximum time between attempts to connect to the controller to
 243 \fIsecs\fR, which must be at least 1.  The actual interval between
 244 connection attempts starts at 1 second and doubles on each failing
 245 attempt until it reaches the maximum.  The default maximum backoff
 246 time is 15 seconds.
 247
 248 .TP
 249 \fB-l\fR, \fB--listen=\fImethod\fR
 250 Configures the switch to additionally listen for incoming OpenFlow
 251 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 252 must be given as one of the following passive OpenFlow connection
 253 methods:
 254
 255 .RS
 256 .TP
 257 \fBpssl:\fR[\fIport\fR]
 258 Listens for SSL connections on \fIport\fR (default: 976).  The
 259 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 260 are mandatory when this form is used.
 261
 262 .TP
 263 \fBptcp:\fR[\fIport\fR]
 264 Listens for TCP connections on \fIport\fR (default: 975).
 265 .RE
 266
 267 .TP
 268 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 269 Specifies a PEM file containing the private key used as the switch's
 270 identity for SSL connections to the controller.
 271
 272 .TP
 273 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 274 Specifies a PEM file containing a certificate, signed by the
 275 controller's certificate authority (CA), that certifies the switch's
 276 private key to identify a trustworthy switch.
 277
 278 .TP
 279 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 280 Specifies a PEM file containing the CA certificate used to verify that
 281 the switch is connected to a trustworthy controller.
 282
 283 .TP
 284 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 285 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 286 the PID of the running process.  If \fIpidfile\fR is not specified, or
 287 if it does not begin with \fB/\fR, then it is created in
 288 \fB@rundir@\fR.
 289
 290 .TP
 291 \fB-D\fR, \fB--detach\fR
 292 Causes \fBsecchan\fR to detach itself from the foreground session and
 293 run as a background process.
 294
 295 .TP
 296 .BR \-h ", " \-\^\-help
 297 Prints a brief help message to the console.
 298
 299 .TP
 300 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 301 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 302 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 303 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 304 special name \fBANY\fR to set the logging levels for all modules.  The
 305 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 306 for logging to the system log or to the console, respectively, or
 307 \fBANY\fR to set the logging levels for both facilities.  If it is
 308 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 309 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 310 the minimum severity of a message for it to be logged.  If it is
 311 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 312
 313 .TP
 314 \fB-v\fR, \fB--verbose\fR
 315 Sets the maximum logging verbosity level, equivalent to
 316 \fB--verbose=ANY:ANY:dbg\fR.
 317
 318 .TP
 319 .BR \-V ", " \-\^\-version
 320 Prints version information to the console.
 321
 322 .SH "SEE ALSO"
 323
 324 .BR dpctl (8),
 325 .BR controller (8),
 326 .BR ofp-pki (8),
 327 .BR vlogconf (8),
 328 .BR switch (8)