pintos-os.org Git - openvswitch/blob - 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-l\Fr, \Fb--listen=\fImethod\fR
 119 Configures the switch to additionally listen for incoming OpenFlow
 120 connections for switch management with \fBdpctl\fR.  The \fImethod\fR
 121 must be given as one of the following passive OpenFlow connection
 122 methods:
 123
 124 .RS
 125 .TP
 126 \fBpssl:\fR[\fIport\fR]
 127 Listens for SSL connections on \fIport\fR (default: 976).  The
 128 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
 129 are mandatory when this form is used.
 130
 131 .TP
 132 \fBptcp:\fR[\fIport\fR]
 133 Listens for TCP connections on \fIport\fR (default: 975).
 134 .RE
 135
 136 .TP
 137 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 138 Specifies a PEM file containing the private key used as the switch's
 139 identity for SSL connections to the controller.
 140
 141 .TP
 142 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 143 Specifies a PEM file containing a certificate, signed by the
 144 controller's certificate authority (CA), that certifies the switch's
 145 private key to identify a trustworthy switch.
 146
 147 .TP
 148 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 149 Specifies a PEM file containing the CA certificate used to verify that
 150 the switch is connected to a trustworthy controller.
 151
 152 .TP
 153 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 154 Causes a file (by default, \fBsecchan.pid\fR) to be created indicating
 155 the PID of the running process.  If \fIpidfile\fR is not specified, or
 156 if it does not begin with \fB/\fR, then it is created in
 157 \fB@rundir@\fR.
 158
 159 .TP
 160 \fB-D\fR, \fB--detach\fR
 161 Causes \fBsecchan\fR to detach itself from the foreground session and
 162 run as a background process.
 163
 164 .TP
 165 .BR \-h ", " \-\^\-help
 166 Prints a brief help message to the console.
 167
 168 .TP
 169 \fB-v\fR \fImodule\fB:\fIfacility\fB:\fIlevel\fR, \fB--verbose=\fImodule\fB:\fIfacility\fB:\fIlevel\fR
 170 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 171 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 172 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 173 special name \fBANY\fR to set the logging levels for all modules.  The
 174 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 175 for logging to the system log or to the console, respectively, or
 176 \fBANY\fR to set the logging levels for both facilities.  The
 177 \fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
 178 \fBdbg\fR, designating the minimum severity of a message for it to be
 179 logged.
 180
 181 .TP
 182 \fB-v\fR, \fB--verbose\fR
 183 Sets the maximum logging verbosity level, equivalent to
 184 \fB--verbose=ANY:ANY:dbg\fR.
 185
 186 .TP
 187 .BR \-V ", " \-\^\-version
 188 Prints version information to the console.
 189
 190 .SH "SEE ALSO"
 191
 192 .BR dpctl (8),
 193 .BR controller (8),
 194 .BR ofp-pki (8),
 195 .BR vlogconf (8),
 196 .BR switch (8)