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 mandatory \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 .SH "CONTACTING THE CONTROLLER"
  36 The OpenFlow switch must be able to contact the OpenFlow controller
  37 over the network.  It can do so in one of two ways:
  38
  39 .IP out-of-band
  40 In this configuration, OpenFlow traffic uses a network separate from
  41 the data traffic that it controls, that is, the switch does not use
  42 any of the network devices added to the datapath with \fBdpctl
  43 addif\fR in its communication with the controller.
  44
  45 To use \fBsecchan\fR in a network with out-of-band control, the
  46 control network must be configured for use by \fBsecchan\fR at the
  47 time it is started.  No additional setup is required.  In particular,
  48 the \fBof\fIn\fR device should not be up or configured with an IP
  49 address (see below).
  50
  51 .IP in-band
  52 In this configuration, a single network is used for OpenFlow traffic
  53 and other data traffic, that is, the switch contacts the controller
  54 over one of the network devices added to the datapath with \fBdpctl
  55 addif\fR.  This configuration is often more convenient than
  56 out-of-band control, because it is not necessary to maintain two
  57 independent networks.
  58
  59 Using \fBsecchan\fR in a network with in-band control requires
  60 additional setup before starting \fBsecchan\fR.  At a minimum, the
  61 special OpenFlow network device \fBof\fIn\fR, where \fIn\fR is same as
  62 the \fIdp_idx\fR specified on the \fBsecchan\fR command line, must be
  63 brought up using
  64 .BR ifconfig (8),
  65 e.g.:
  66 .RS
  67 .IP
  68 ifconfig of0 up
  69 .RE
  70 .IP
  71 Before \fBsecchan\fR starts, the \fBof\fIn\fR device cannot send or
  72 receive any packets, so the next step depends on whether connectivity
  73 is required to configure the device's IP address.  If the switch has a
  74 static IP address, you may configure its IP address now with a command
  75 such as:
  76 .RS
  77 .IP
  78 ifconfig of0 192.168.1.1
  79 .RE
  80 .IP
  81 and then invoke \fBsecchan\fR.
  82
  83 On the other hand, if the switch does not have a static IP address,
  84 e.g. it obtains its IP address dynamically via DHCP, the DHCP client
  85 will not be able to contact the DHCP server until the secure channel
  86 has started up.  Thus, start \fBsecchan\fR without configuring
  87 \fBof\fIn\fR further, and start the DHCP client afterward.
  88
  89 .SH OPTIONS
  90 .TP
  91 \fB-f\fR, \fB--fail=\fR[\fBopen\fR|\fBclosed\fR]
  92 The controller is, ordinarily, responsible for setting up all flows on
  93 the OpenFlow switch.  Thus, if the connection to the controller fails,
  94 no new network connections can be set up.  If the connection to the
  95 controller stays down long enough, no packets can pass through the
  96 switch at all.
  97
  98 If this option is set to \fBopen\fR (the default), \fBsecchan\fR will
  99 take over responsibility for setting up flows in the local datapath
 100 when no message has been received from the controller for three times
 101 the inactivity probe interval (see below), or 45 seconds by default.
 102 In this ``fail open'' mode, \fBsecchan\fR causes the datapath to act
 103 like an ordinary MAC-learning switch.  \fBsecchan\fR will continue to
 104 retry connection to the controller in the background and, when the
 105 connection succeeds, it discontinues its fail-open behavior.  The
 106 secure channel enters the fail-open mode when
 107
 108 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
 109 set up flows on its own when the controller connection fails.
 110
 111 .TP
 112 \fB--inactivity-probe=\fIsecs\fR
 113 When the secure channel is connected to the controller, the secure
 114 channel waits for a message to be received from the controller for
 115 \fIsecs\fR seconds before it sends a inactivity probe to the
 116 controller.  After sending the inactivity probe, if no response is
 117 received for an additional \fIsecs\fR seconds, the secure channel
 118 assumes that the connection has been broken and attempts to reconnect.
 119 The default is 15 seconds, and the minimum value is 5 seconds.
 120
 121 When fail-open mode is configured, changing the inactivity probe
 122 interval also changes the interval before entering fail-open mode (see
 123 above).
 124
 125 .TP
 126 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 127 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 128 secure channel will remain in the switch's flow table without any
 129 matching packets being seen.  If \fBpermanent\fR is specified, which
 130 is not recommended, flows set up by the secure channel will never
 131 expire.  The default is 15 seconds.
 132
 133 Most flows are set up by the OpenFlow controller, not by the secure
 134 channel.  This option affects only the following flows, which the
 135 secure channel sets up itself:
 136
 137 .RS
 138 .IP \(bu
 139 When \fB--fail=open\fR is specified, flows set up when the secure
 140 channel has not been able to contact the controller for the configured
 141 fail-open delay.
 142
 143 .IP \(bu
 144 When in-band control is in use, flows set up to bootstrap contacting
 145 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
 146 more information about in-band control).
 147 .RE
 148
 149 .IP
 150 As a result, when both \fB--fail=open\fR and in-band control are not
 151 in use, this option has no effect.
 152
 153 .TP
 154 \fB--max-backoff=\fIsecs\fR
 155 Sets the maximum time between attempts to connect to the controller to
 156 \fIsecs\fR, which must be at least 1.  The actual interval between
 157 connection attempts starts at 1 second and doubles on each failing
 158 attempt until it reaches the maximum.  The default maximum backoff
 159 time is 15 seconds.
 160
 161 .TP
 162 \fB-l\fR, \fB--listen=\fImethod\fR
 163 Configures the switch to additionally listen for incoming OpenFlow
 164 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 165 must be given as one of the following passive OpenFlow connection
 166 methods:
 167
 168 .RS
 169 .TP
 170 \fBpssl:\fR[\fIport\fR]
 171 Listens for SSL connections on \fIport\fR (default: 976).  The
 172 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 173 are mandatory when this form is used.
 174
 175 .TP
 176 \fBptcp:\fR[\fIport\fR]
 177 Listens for TCP connections on \fIport\fR (default: 975).
 178 .RE
 179
 180 .TP
 181 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 182 Specifies a PEM file containing the private key used as the switch's
 183 identity for SSL connections to the controller.
 184
 185 .TP
 186 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 187 Specifies a PEM file containing a certificate, signed by the
 188 controller's certificate authority (CA), that certifies the switch's
 189 private key to identify a trustworthy switch.
 190
 191 .TP
 192 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 193 Specifies a PEM file containing the CA certificate used to verify that
 194 the switch is connected to a trustworthy controller.
 195
 196 .TP
 197 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 198 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 199 the PID of the running process.  If \fIpidfile\fR is not specified, or
 200 if it does not begin with \fB/\fR, then it is created in
 201 \fB@rundir@\fR.
 202
 203 .TP
 204 \fB-D\fR, \fB--detach\fR
 205 Causes \fBsecchan\fR to detach itself from the foreground session and
 206 run as a background process.
 207
 208 .TP
 209 .BR \-h ", " \-\^\-help
 210 Prints a brief help message to the console.
 211
 212 .TP
 213 \fB-v\fR \fImodule\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\fB:\fIlevel\fR
 214 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 215 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 216 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 217 special name \fBANY\fR to set the logging levels for all modules.  The
 218 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 219 for logging to the system log or to the console, respectively, or
 220 \fBANY\fR to set the logging levels for both facilities.  The
 221 \fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
 222 \fBdbg\fR, designating the minimum severity of a message for it to be
 223 logged.
 224
 225 .TP
 226 \fB-v\fR, \fB--verbose\fR
 227 Sets the maximum logging verbosity level, equivalent to
 228 \fB--verbose=ANY:ANY:dbg\fR.
 229
 230 .TP
 231 .BR \-V ", " \-\^\-version
 232 Prints version information to the console.
 233
 234 .SH "SEE ALSO"
 235
 236 .BR dpctl (8),
 237 .BR controller (8),
 238 .BR ofp-pki (8),
 239 .BR vlogconf (8),
 240 .BR switch (8)