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--no-resolv-conf\fR
 189 When \fBsecchan\fR performs controller discovery (see \fBCONTACTING
 190 THE CONTROLLER\fR, above, for more information about controller
 191 discovery), by default it overwrites the system's
 192 \fB/etc/resolv.conf\fR with domain information and DNS servers
 193 obtained via DHCP.  If the location of the controller is specified
 194 using a hostname, rather than an IP address, and the network's DNS
 195 servers ever change, this behavior is essential.  But because it also
 196 interferes with any administrator or process that manages
 197 \fB/etc/resolv.conf\fR, when this option is specified, \fBsecchan\fR
 198 will not modify \fB/etc/resolv.conf\fR.
 199
 200 \fBsecchan\fR will only modify \fBresolv.conf\fR if the DHCP response
 201 that it receives specifies one or more DNS servers.
 202
 203 When controller discovery is not performed, this option has no effect.
 204
 205 .TP
 206 \fB-f\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
 207 The controller is, ordinarily, responsible for setting up all flows on
 208 the OpenFlow switch.  Thus, if the connection to the controller fails,
 209 no new network connections can be set up.  If the connection to the
 210 controller stays down long enough, no packets can pass through the
 211 switch at all.
 212
 213 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
 214 take over responsibility for setting up flows in the local datapath
 215 when no message has been received from the controller for three times
 216 the inactivity probe interval (see below), or 45 seconds by default.
 217 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
 218 like an ordinary MAC-learning switch.  \fBsecchan\fR will continue to
 219 retry connection to the controller in the background and, when the
 220 connection succeeds, it discontinues its fail-open behavior.  The
 221 secure channel enters the fail-open mode when
 222
 223 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
 224 set up flows on its own when the controller connection fails.
 225
 226 .TP
 227 \fB--inactivity-probe=\fIsecs\fR
 228 When the secure channel is connected to the controller, the secure
 229 channel waits for a message to be received from the controller for
 230 \fIsecs\fR seconds before it sends a inactivity probe to the
 231 controller.  After sending the inactivity probe, if no response is
 232 received for an additional \fIsecs\fR seconds, the secure channel
 233 assumes that the connection has been broken and attempts to reconnect.
 234 The default is 15 seconds, and the minimum value is 5 seconds.
 235
 236 When fail-open mode is configured, changing the inactivity probe
 237 interval also changes the interval before entering fail-open mode (see
 238 above).
 239
 240 .TP
 241 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 242 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 243 secure channel will remain in the switch's flow table without any
 244 matching packets being seen.  If \fBpermanent\fR is specified, which
 245 is not recommended, flows set up by the secure channel will never
 246 expire.  The default is 15 seconds.
 247
 248 Most flows are set up by the OpenFlow controller, not by the secure
 249 channel.  This option affects only the following flows, which the
 250 secure channel sets up itself:
 251
 252 .RS
 253 .IP \(bu
 254 When \fB--fail=open\fR is specified, flows set up when the secure
 255 channel has not been able to contact the controller for the configured
 256 fail-open delay.
 257
 258 .IP \(bu
 259 When in-band control is in use, flows set up to bootstrap contacting
 260 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
 261 more information about in-band control).
 262 .RE
 263
 264 .IP
 265 As a result, when both \fB--fail=open\fR and in-band control are not
 266 in use, this option has no effect.
 267
 268 .TP
 269 \fB--max-backoff=\fIsecs\fR
 270 Sets the maximum time between attempts to connect to the controller to
 271 \fIsecs\fR, which must be at least 1.  The actual interval between
 272 connection attempts starts at 1 second and doubles on each failing
 273 attempt until it reaches the maximum.  The default maximum backoff
 274 time is 15 seconds.
 275
 276 .TP
 277 \fB-l\fR, \fB--listen=\fImethod\fR
 278 Configures the switch to additionally listen for incoming OpenFlow
 279 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 280 must be given as one of the following passive OpenFlow connection
 281 methods:
 282
 283 .RS
 284 .TP
 285 \fBpssl:\fR[\fIport\fR]
 286 Listens for SSL connections on \fIport\fR (default: 976).  The
 287 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 288 are mandatory when this form is used.
 289
 290 .TP
 291 \fBptcp:\fR[\fIport\fR]
 292 Listens for TCP connections on \fIport\fR (default: 975).
 293 .RE
 294
 295 .TP
 296 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 297 Specifies a PEM file containing the private key used as the switch's
 298 identity for SSL connections to the controller.
 299
 300 .TP
 301 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 302 Specifies a PEM file containing a certificate, signed by the
 303 controller's certificate authority (CA), that certifies the switch's
 304 private key to identify a trustworthy switch.
 305
 306 .TP
 307 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 308 Specifies a PEM file containing the CA certificate used to verify that
 309 the switch is connected to a trustworthy controller.
 310
 311 .TP
 312 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 313 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 314 the PID of the running process.  If \fIpidfile\fR is not specified, or
 315 if it does not begin with \fB/\fR, then it is created in
 316 \fB@rundir@\fR.
 317
 318 .TP
 319 \fB-D\fR, \fB--detach\fR
 320 Causes \fBsecchan\fR to detach itself from the foreground session and
 321 run as a background process.
 322
 323 .TP
 324 .BR \-h ", " \-\^\-help
 325 Prints a brief help message to the console.
 326
 327 .TP
 328 \fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 329 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 330 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 331 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 332 special name \fBANY\fR to set the logging levels for all modules.  The
 333 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 334 for logging to the system log or to the console, respectively, or
 335 \fBANY\fR to set the logging levels for both facilities.  If it is
 336 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 337 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 338 the minimum severity of a message for it to be logged.  If it is
 339 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 340
 341 .TP
 342 \fB-v\fR, \fB--verbose\fR
 343 Sets the maximum logging verbosity level, equivalent to
 344 \fB--verbose=ANY:ANY:dbg\fR.
 345
 346 .TP
 347 .BR \-V ", " \-\^\-version
 348 Prints version information to the console.
 349
 350 .SH "SEE ALSO"
 351
 352 .BR dpctl (8),
 353 .BR ofp-discover (8),
 354 .BR controller (8),
 355 .BR ofp-pki (8),
 356 .BR vlogconf (8),
 357 .BR switch (8)