switch/switch.8.in

   1 .TH secchan 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 switch \- userspace implementation of OpenFlow switch
   5
   6 .SH SYNOPSIS
   7 .B switch
   8 [\fIoptions\fR]
   9 \fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR]...
  10 \fIcontroller\fR
  11
  12 .SH DESCRIPTION
  13 The \fBswitch\fR is a userspace implementation of an OpenFlow switch.
  14 It implements all three parts of the OpenFlow switch specification: a
  15 ``flow table'' in which each flow entry is associated with an action
  16 telling the switch how to process the flow; a ``secure channel''
  17 connecting the switch to a remote process (a controller), allowing
  18 commands and packets to be sent between the controller and the switch;
  19 and an OpenFlow protocol implementation.
  20
  21 \fBswitch\fR monitors one or more network device interfaces,
  22 forwarding packets between them according to the entries in the flow
  23 table.  It also maintains a connection to an OpenFlow controller over
  24 a TCP or SSL connection, relaying packets that do not match a flow
  25 table entry to the controller and executing commands sent by the
  26 controller.
  27
  28 For access to network devices, the switch program must normally run as
  29 root.
  30
  31 The mandatory \fIcontroller\fR argument specifies how to connect to
  32 the OpenFlow controller.  It takes one of the following forms:
  33
  34 .TP
  35 \fBssl:\fIhost\fR[\fB:\fIport\fR]
  36 The specified SSL \fIport\fR (default: 6633) on the given remote
  37 \fIhost\fR.  The \fB--private-key\fR, \fB--certificate\fR, and
  38 \fB--ca-cert\fR options are mandatory when this form is used.
  39
  40 .TP
  41 \fBtcp:\fIhost\fR[\fB:\fIport\fR]
  42 The specified TCP \fIport\fR (default: 6633) on the given remote
  43 \fIhost\fR.
  44
  45 .TP
  46 \fBunix:\fIfile\fR
  47 The Unix domain server socket named \fIfile\fR.
  48
  49 .SH OPTIONS
  50 .TP
  51 \fB-i\fR, \fB--interfaces=\fR\fInetdev\fR[\fB,\fInetdev\fR]...
  52 Specifies each \fInetdev\fR (e.g., \fBeth0\fR) as a switch port.  The
  53 specified network devices should not have any configured IP addresses.
  54 This option may be given any number of times to specify additional
  55 network devices.
  56
  57 .TP
  58 \fB-d\fR, \fB--datapath-id=\fIdpid\fR
  59 Specifies the OpenFlow switch ID (a 48-bit number that uniquely
  60 identifies a controller) as \fIdpid\fR, which consists of exactly 12
  61 hex digits.  Without this option, \fBswitch\fR picks an ID randomly.
  62
  63 .TP
  64 \fB--max-backoff=\fIsecs\fR
  65 Sets the maximum time between attempts to connect to the controller to
  66 \fIsecs\fR, which must be at least 1.  The actual interval between
  67 connection attempts starts at 1 second and doubles on each failing
  68 attempt until it reaches the maximum.  The default maximum backoff
  69 time is 15 seconds.
  70
  71 .TP
  72 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
  73 Specifies a PEM file containing the private key used as the switch's
  74 identity for SSL connections to the controller.
  75
  76 .TP
  77 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
  78 Specifies a PEM file containing a certificate, signed by the
  79 controller's certificate authority (CA), that certifies the switch's
  80 private key to identify a trustworthy switch.
  81
  82 .TP
  83 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
  84 Specifies a PEM file containing the CA certificate used to verify that
  85 the switch is connected to a trustworthy controller.
  86
  87 .TP
  88 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
  89 Causes a file (by default, \fBswitch.pid\fR) to be created indicating
  90 the PID of the running process.  If \fIpidfile\fR is not specified, or
  91 if it does not begin with \fB/\fR, then it is created in
  92 \fB@rundir@\fR.
  93
  94 .TP
  95 \fB-f\fR, \fB--force\fR
  96 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
  97 specified pidfile already exists and is locked by a running process,
  98 \fBswitch\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
  99 to cause it to instead overwrite the pidfile.
 100
 101 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 102 effect.
 103
 104 .TP
 105 \fB-D\fR, \fB--detach\fR
 106 Causes \fBswitch\fR to detach itself from the foreground session and
 107 run as a background process.
 108
 109 .TP
 110 .BR \-h ", " \-\^\-help
 111 Prints a brief help message to the console.
 112
 113 .TP
 114 \fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 115 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 116 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 117 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 118 special name \fBANY\fR to set the logging levels for all modules.  The
 119 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 120 for logging to the system log or to the console, respectively, or
 121 \fBANY\fR to set the logging levels for both facilities.  If it is
 122 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 123 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 124 the minimum severity of a message for it to be logged.  If it is
 125 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 126
 127 .TP
 128 \fB-v\fR, \fB--verbose\fR
 129 Sets the maximum logging verbosity level, equivalent to
 130 \fB--verbose=ANY:ANY:dbg\fR.
 131
 132 .TP
 133 \fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
 134 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
 135 \fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
 136
 137 .TP
 138 .BR \-V ", " \-\^\-version
 139 Prints version information to the console.
 140
 141 .SH BUGS
 142
 143 The userspace switch implementation lags significantly behind the
 144 kernel-based switch, both in implementation quality and performance.
 145 It should only be used when the kernel-based switch cannot be.
 146
 147 General-purpose support for VLAN tag rewriting is precluded by the
 148 Linux kernel AF_PACKET implementation.
 149
 150 .SH "SEE ALSO"
 151
 152 .BR dpctl (8),
 153 .BR ofp-pki (8),
 154 .BR controller (8),
 155 .BR vlogconf (8)