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 the controller connection stays down for long enough.  In this
 101 ``fail open'' mode, \fBsecchan\fR causes the datapath to act like an
 102 ordinary MAC-learning switch.  \fBsecchan\fR will continue to retry
 103 connection to the controller in the background and, when the
 104 connection succeeds, it discontinues its fail-open behavior.
 105
 106 If this option is set to \fBclosed\fR, then \fBsecchan\fR will not
 107 set up flows on its own when the controller connection fails.
 108
 109 .TP
 110 \fB-d\fR, \fB--fail-open-delay=\fIsecs\fR
 111 Sets the number of seconds of failed controller connection attempts
 112 after which the switch enters fail-open mode.  The default is 30
 113 seconds.
 114
 115 This option has no effect when \fB--fail=closed\fR is specified.
 116
 117 .TP
 118 \fB--max-idle=\fIsecs\fR|\fBpermanent\fR
 119 Sets \fIsecs\fR as the number of seconds that a flow set up by the
 120 secure channel will remain in the switch's flow table without any
 121 matching packets being seen.  If \fBpermanent\fR is specified, which
 122 is not recommended, flows set up by the secure channel will never
 123 expire.  The default is 15 seconds.
 124
 125 Most flows are set up by the OpenFlow controller, not by the secure
 126 channel.  This option affects only the following flows, which the
 127 secure channel sets up itself:
 128
 129 .RS
 130 .IP \(bu
 131 When \fB--fail=open\fR is specified, flows set up when the secure
 132 channel has not been able to contact the controller for the configured
 133 fail-open delay.
 134
 135 .IP \(bu
 136 When in-band control is in use, flows set up to bootstrap contacting
 137 the controller (see \fBCONTACTING THE CONTROLLER\fR, above, for
 138 more information about in-band control).
 139 .RE
 140
 141 .IP
 142 As a result, when both \fB--fail=open\fR and in-band control are not
 143 in use, this option has no effect.
 144
 145 .TP
 146 \fB-l\fR, \fB--listen=\fImethod\fR
 147 Configures the switch to additionally listen for incoming OpenFlow
 148 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 149 must be given as one of the following passive OpenFlow connection
 150 methods:
 151
 152 .RS
 153 .TP
 154 \fBpssl:\fR[\fIport\fR]
 155 Listens for SSL connections on \fIport\fR (default: 976).  The
 156 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 157 are mandatory when this form is used.
 158
 159 .TP
 160 \fBptcp:\fR[\fIport\fR]
 161 Listens for TCP connections on \fIport\fR (default: 975).
 162 .RE
 163
 164 .TP
 165 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 166 Specifies a PEM file containing the private key used as the switch's
 167 identity for SSL connections to the controller.
 168
 169 .TP
 170 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 171 Specifies a PEM file containing a certificate, signed by the
 172 controller's certificate authority (CA), that certifies the switch's
 173 private key to identify a trustworthy switch.
 174
 175 .TP
 176 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 177 Specifies a PEM file containing the CA certificate used to verify that
 178 the switch is connected to a trustworthy controller.
 179
 180 .TP
 181 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 182 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 183 the PID of the running process.  If \fIpidfile\fR is not specified, or
 184 if it does not begin with \fB/\fR, then it is created in
 185 \fB@rundir@\fR.
 186
 187 .TP
 188 \fB-D\fR, \fB--detach\fR
 189 Causes \fBsecchan\fR to detach itself from the foreground session and
 190 run as a background process.
 191
 192 .TP
 193 .BR \-h ", " \-\^\-help
 194 Prints a brief help message to the console.
 195
 196 .TP
 197 \fB-v\fR \fImodule\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\fB:\fIlevel\fR
 198 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 199 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 200 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 201 special name \fBANY\fR to set the logging levels for all modules.  The
 202 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 203 for logging to the system log or to the console, respectively, or
 204 \fBANY\fR to set the logging levels for both facilities.  The
 205 \fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
 206 \fBdbg\fR, designating the minimum severity of a message for it to be
 207 logged.
 208
 209 .TP
 210 \fB-v\fR, \fB--verbose\fR
 211 Sets the maximum logging verbosity level, equivalent to
 212 \fB--verbose=ANY:ANY:dbg\fR.
 213
 214 .TP
 215 .BR \-V ", " \-\^\-version
 216 Prints version information to the console.
 217
 218 .SH "SEE ALSO"
 219
 220 .BR dpctl (8),
 221 .BR controller (8),
 222 .BR ofp-pki (8),
 223 .BR vlogconf (8),
 224 .BR switch (8)