udatapath/udatapath.8.in

   1 .TH udatapath 8 "May 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 udatapath \- userspace implementation of datapath for OpenFlow switch
   5
   6 .SH SYNOPSIS
   7 .B udatapath
   8 [\fIoptions\fR]
   9 \fB-i\fR \fInetdev\fR[\fB,\fInetdev\fR].\|.\|.
  10 \fImethod\fR [\fImethod\fR].\|.\|.
  11
  12 .SH DESCRIPTION
  13 The \fBudatapath\fR is a userspace implementation of an OpenFlow
  14 datapath.  It monitors one or more network device interfaces,
  15 forwarding packets between them according to the entries in the flow
  16 table that it maintains.  When it is used with \fBsecchan\fR(8), to
  17 connect the datapath to an OpenFlow controller, the combination is an
  18 OpenFlow switch.
  19
  20 For access to network devices, the udatapath program must normally run as
  21 root.
  22
  23 The mandatory \fImethod\fR argument specifies how \fBsecchan\fR(8)
  24 communicates with \fBudatapath\fR, as a passive OpenFlow connection
  25 method.  Ordinarily \fImethod\fR takes the following form:
  26
  27 .TP
  28 \fBpunix:\fIfile\fR
  29 Listens for connections on the Unix domain server socket named
  30 \fIfile\fR.
  31
  32 .PP
  33 The following connection methods are also supported, but their use
  34 would be unusual because \fBudatapath\fR and \fBsecchan\fR should run
  35 on the same machine:
  36
  37 .TP
  38 \fBpssl:\fR[\fIport\fR]
  39 Listens for SSL connections \fIport\fR (default: 976).  The
  40 \fB--private-key\fR, \fB--certificate\fR, and \fB--ca-cert\fR options
  41 are mandatory when this form is used.  (\fBofp\-pki\fR(8) does not set
  42 up a suitable PKI for use with this option.)
  43
  44 .TP
  45 \fBptcp:\fR[\fIport\fR]
  46 Listens for TCP connections from remote OpenFlow switches on
  47 \fIport\fR (default: 975).
  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-L\fR, \fB--local-port=\fInetdev\fR
  59 Specifies the network device to use as the userspace datapath's
  60 ``local port,'' which is a network device that \fBsecchan\fR(8)
  61 bridges to the physical switch ports for use in in-band control.  When
  62 this option is not specified, the default is \fBtap:\fR, which causes
  63 a new TAP virtual network device to be allocated with a default name
  64 assigned by the kernel.  To do the same, but assign a specific name
  65 \fBname\fR to the TAP network device, specify the option as
  66 \fB--local-port=tap:\fIname\fR.
  67
  68 Either way, the existence of TAP devices created by \fBudatapath\fR is
  69 temporary: they are destroyed when \fBudatapath\fR exits.  If this is
  70 undesirable, you may use \fBtunctl\fR(8) to create a persistent TAP
  71 network device and then pass it to \fBudatapath\fR, like so:
  72
  73 .RS
  74 .IP 1.
  75 Create a persistent TAP network device: \fBtunctl -t mytap\fR.  (The
  76 \fBtunctl\fR(8) utility is part of User Mode Linux.  It is not
  77 included with the OpenFlow reference implementation.)
  78 .IP 2.
  79 Invoke \fBudatapath\fR(8) using \fBmytap\fR, e.g. \fBudatapath
  80 --local-port=mytap\fR .\|.\|.  (Note the lack of \fBtap:\fR prefix on
  81 the \fB--local-port\fR argument.)
  82 .IP 3.
  83 Invoke \fBsecchan\fR(8), etc., and use the switch as desired.
  84 .IP 4.
  85 When \fBsecchan\fR and \fBudatapath\fR have terminated and the TAP
  86 network device is no longer needed, you may destroy it with: \fBtunctl
  87 -d mytap\fR
  88 .RE
  89
  90 .IP
  91 It does not ordinarily make sense to specify the name of a physical
  92 network device on \fB-L\fR or \fB--local-port\fR.
  93
  94 .TP
  95 \fB--no-local-port\fR
  96 Do not provide a local port as part of the datapath.  When this option
  97 is used, the switch will not support in-band control.
  98
  99 .TP
 100 \fB-d\fR, \fB--datapath-id=\fIdpid\fR
 101 Specifies the OpenFlow datapath ID (a 48-bit number that uniquely
 102 identifies a controller) as \fIdpid\fR, which consists of exactly 12
 103 hex digits.  Without this option, \fBudatapath\fR picks an ID randomly.
 104
 105 .TP
 106 \fB-p\fR, \fB--private-key=\fIprivkey.pem\fR
 107 Specifies a PEM file containing the private key used as the datapath's
 108 identity for SSL connections to \fBsecchan\fR(8).
 109
 110 .TP
 111 \fB-c\fR, \fB--certificate=\fIcert.pem\fR
 112 Specifies a PEM file containing a certificate, signed by the
 113 datapath's certificate authority (CA), that certifies the datapath's
 114 private key to identify a trustworthy datapath.
 115
 116 .TP
 117 \fB-C\fR, \fB--ca-cert=\fIcacert.pem\fR
 118 Specifies a PEM file containing the CA certificate used to verify that
 119 the datapath is connected to a trustworthy secure channel.
 120
 121 .TP
 122 \fB-P\fR[\fIpidfile\fR], \fB--pidfile\fR[\fB=\fIpidfile\fR]
 123 Causes a file (by default, \fBudatapath.pid\fR) to be created indicating
 124 the PID of the running process.  If \fIpidfile\fR is not specified, or
 125 if it does not begin with \fB/\fR, then it is created in
 126 \fB@RUNDIR@\fR.
 127
 128 .TP
 129 \fB-f\fR, \fB--force\fR
 130 By default, when \fB-P\fR or \fB--pidfile\fR is specified and the
 131 specified pidfile already exists and is locked by a running process,
 132 \fBudatapath\fR refuses to start.  Specify \fB-f\fR or \fB--force\fR
 133 to cause it to instead overwrite the pidfile.
 134
 135 When \fB-P\fR or \fB--pidfile\fR is not specified, this option has no
 136 effect.
 137
 138 .TP
 139 \fB-D\fR, \fB--detach\fR
 140 Causes \fBudatapath\fR to detach itself from the foreground session and
 141 run as a background process.
 142
 143 .TP
 144 .BR \-h ", " \-\^\-help
 145 Prints a brief help message to the console.
 146
 147 .TP
 148 \fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
 149 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 150 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 151 displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
 152 special name \fBANY\fR to set the logging levels for all modules.  The
 153 \fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
 154 for logging to the system log or to the console, respectively, or
 155 \fBANY\fR to set the logging levels for both facilities.  If it is
 156 omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
 157 be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
 158 the minimum severity of a message for it to be logged.  If it is
 159 omitted, \fIlevel\fR defaults to \fBdbg\fR.
 160
 161 .TP
 162 \fB-v\fR, \fB--verbose\fR
 163 Sets the maximum logging verbosity level, equivalent to
 164 \fB--verbose=ANY:ANY:dbg\fR.
 165
 166 .TP
 167 .BR \-V ", " \-\^\-version
 168 Prints version information to the console.
 169
 170 .SH BUGS
 171 The userspace datapath's performance lags significantly behind that of
 172 the kernel-based switch.  It should only be used when the kernel-based
 173 switch cannot be.
 174
 175 On Linux, general-purpose support for VLAN tag rewriting is precluded
 176 by the Linux kernel AF_PACKET implementation.
 177
 178 .SH "SEE ALSO"
 179
 180 .BR secchan (8),
 181 .BR dpctl (8),
 182 .BR controller (8),
 183 .BR vlogconf (8).