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