vswitchd/ovs-vswitchd.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovs\-vswitchd 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
   8 .\" This program's name:
   9 .ds PN ovs\-vswitchd
  10 .
  11 .SH NAME
  12 ovs\-vswitchd \- Open vSwitch daemon
  13 .
  14 .SH SYNOPSIS
  15 \fBovs\-vswitchd \fR[\fIdatabase\fR]
  16 .
  17 .SH DESCRIPTION
  18 A daemon that manages and controls any number of Open vSwitch switches
  19 on the local machine.
  20 .PP
  21 The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects
  22 to \fBovsdb\-server\fR.  The default is \fBunix:@RUNDIR@/db.sock\fR.
  23 The following forms are accepted:
  24 .so ovsdb/remote-active.man
  25 .so ovsdb/remote-passive.man
  26 .PP
  27 \fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at
  28 startup.  It sets up Open vSwitch datapaths and then operates
  29 switching across each bridge described in its configuration files.  As
  30 the database changes, \fBovs\-vswitchd\fR automatically updates its
  31 configuration to match.
  32 .PP
  33 \fBovs\-vswitchd\fR switches may be configured with any of the following
  34 features:
  35 .
  36 .IP \(bu
  37 L2 switching with MAC learning.
  38 .
  39 .IP \(bu
  40 NIC bonding with automatic fail-over and source MAC-based TX load
  41 balancing ("SLB").
  42 .
  43 .IP \(bu
  44 802.1Q VLAN support.
  45 .
  46 .IP \(bu
  47 Port mirroring, with optional VLAN tagging.
  48 .
  49 .IP \(bu
  50 NetFlow v5 flow logging.
  51 .
  52 .IP \(bu
  53 sFlow(R) monitoring.
  54 .
  55 .IP \(bu
  56 Connectivity to an external OpenFlow controller, such as NOX.
  57 .
  58 .PP
  59 Only a single instance of \fBovs\-vswitchd\fR is intended to run at a time.
  60 A single \fBovs\-vswitchd\fR can manage any number of switch instances, up
  61 to the maximum number of supported Open vSwitch datapaths.
  62 .PP
  63 \fBovs\-vswitchd\fR does all the necessary management of Open vSwitch datapaths
  64 itself.  Thus, external tools, such \fBovs\-dpctl\fR(8), are not needed for
  65 managing datapaths in conjunction with \fBovs\-vswitchd\fR, and their use
  66 to modify datapaths when \fBovs\-vswitchd\fR is running can interfere with
  67 its operation.  (\fBovs\-dpctl\fR may still be useful for diagnostics.)
  68 .PP
  69 An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR
  70 to be useful.  Please refer to the \fBINSTALL.Linux\fR file included in the
  71 Open vSwitch distribution for instructions on how to build and load
  72 the Open vSwitch kernel module.
  73 .PP
  74 .SH OPTIONS
  75 .IP "\fB\-\-mlockall\fR"
  76 Causes \fBovs\-vswitchd\fR to call the \fBmlockall()\fR function, to
  77 attempt to lock all of its process memory into physical RAM,
  78 preventing the kernel from paging any of its memory to disk.  This
  79 helps to avoid networking interruptions due to system memory pressure.
  80 .IP
  81 Some systems do not support \fBmlockall()\fR at all, and other systems
  82 only allow privileged users, such as the superuser, to use it.
  83 \fBovs\-vswitchd\fR emits a log message if \fBmlockall()\fR is
  84 unavailable or unsuccessful.
  85 .
  86 .SS "DPDK Options"
  87 .IP "\fB\-\-dpdk\fR"
  88 Initialize \fBovs\-vswitchd\fR DPDK datapath.  Refer to INSTALL.DPDK
  89 for details.
  90 .SS "Daemon Options"
  91 .ds DD \
  92 \fBovs\-vswitchd\fR detaches only after it has connected to the \
  93 database, retrieved the initial configuration, and set up that \
  94 configuration.
  95 .so lib/daemon.man
  96 .SS "Service Options"
  97 .so lib/service.man
  98 .SS "Public Key Infrastructure Options"
  99 .so lib/ssl.man
 100 .so lib/ssl-bootstrap.man
 101 .SS "Logging Options"
 102 .so lib/vlog.man
 103 .SS "Other Options"
 104 .so lib/unixctl.man
 105 .so lib/common.man
 106 .
 107 .SH "RUNTIME MANAGEMENT COMMANDS"
 108 \fBovs\-appctl\fR(8) can send commands to a running
 109 \fBovs\-vswitchd\fR process.  The currently supported commands are
 110 described below.  The command descriptions assume an understanding of
 111 how to configure Open vSwitch.
 112 .SS "GENERAL COMMANDS"
 113 .IP "\fBexit\fR"
 114 Causes \fBovs\-vswitchd\fR to gracefully terminate.
 115 .IP "\fBqos/show\fR \fIinterface\fR"
 116 Queries the kernel for Quality of Service configuration and statistics
 117 associated with the given \fIinterface\fR.
 118 .IP "\fBbfd/show\fR [\fIinterface\fR]"
 119 Displays detailed information about Bidirectional Forwarding Detection
 120 configured on \fIinterface\fR.  If \fIinterface\fR is not specified,
 121 then displays detailed information about all interfaces with BFD
 122 enabled.
 123 .IP "\fBbfd/set-forwarding\fR [\fIinterface\fR] \fIstatus\fR"
 124 Force the fault status of the BFD module on \fIinterface\fR (or all
 125 interfaces if none is given) to be \fIstatus\fR.  \fIstatus\fR can be
 126 "true", "false", or "normal" which reverts to the standard behavior.
 127 .IP "\fBcfm/show\fR [\fIinterface\fR]"
 128 Displays detailed information about Connectivity Fault Management
 129 configured on \fIinterface\fR.  If \fIinterface\fR is not specified,
 130 then displays detailed information about all interfaces with CFM
 131 enabled.
 132 .IP "\fBcfm/set-fault\fR [\fIinterface\fR] \fIstatus\fR"
 133 Force the fault status of the CFM module on \fIinterface\fR (or all
 134 interfaces if none is given) to be \fIstatus\fR.  \fIstatus\fR can be
 135 "true", "false", or "normal" which reverts to the standard behavior.
 136 .IP "\fBstp/tcn\fR [\fIbridge\fR]"
 137 Forces a topology change event on \fIbridge\fR if it's running STP.  This
 138 may cause it to send Topology Change Notifications to its peers and flush
 139 its MAC table..  If no \fIbridge\fR is given, forces a topology change
 140 event on all bridges.
 141 .SS "BRIDGE COMMANDS"
 142 These commands manage bridges.
 143 .IP "\fBfdb/flush\fR [\fIbridge\fR]"
 144 Flushes \fIbridge\fR MAC address learning table, or all learning tables
 145 if no \fIbridge\fR is given.
 146 .IP "\fBfdb/show\fR \fIbridge\fR"
 147 Lists each MAC address/VLAN pair learned by the specified \fIbridge\fR,
 148 along with the port on which it was learned and the age of the entry,
 149 in seconds.
 150 .IP "\fBmdb/flush\fR [\fIbridge\fR]"
 151 Flushes \fIbridge\fR multicast snooping table, or all snooping tables
 152 if no \fIbridge\fR is given.
 153 .IP "\fBmdb/show\fR \fIbridge\fR"
 154 Lists each multicast group/VLAN pair learned by the specified \fIbridge\fR,
 155 along with the port on which it was learned and the age of the entry,
 156 in seconds.
 157 .IP "\fBbridge/reconnect\fR [\fIbridge\fR]"
 158 Makes \fIbridge\fR drop all of its OpenFlow controller connections and
 159 reconnect.  If \fIbridge\fR is not specified, then all bridges drop
 160 their controller connections and reconnect.
 161 .IP
 162 This command might be useful for debugging OpenFlow controller issues.
 163 .
 164 .IP "\fBbridge/dump\-flows\fR \fIbridge\fR"
 165 Lists all flows in \fIbridge\fR, including those normally hidden to
 166 commands such as \fBovs\-ofctl dump\-flows\fR.  Flows set up by mechanisms
 167 such as in-band control and fail-open are hidden from the controller
 168 since it is not allowed to modify or override them.
 169 .SS "BOND COMMANDS"
 170 These commands manage bonded ports on an Open vSwitch's bridges.  To
 171 understand some of these commands, it is important to understand a
 172 detail of the bonding implementation called ``source load balancing''
 173 (SLB).  Instead of directly assigning Ethernet source addresses to
 174 slaves, the bonding implementation computes a function that maps an
 175 48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash''
 176 value).  All of the Ethernet addresses that map to a single 8-bit
 177 value are then assigned to a single slave.
 178 .IP "\fBbond/list\fR"
 179 Lists all of the bonds, and their slaves, on each bridge.
 180 .
 181 .IP "\fBbond/show\fR [\fIport\fR]"
 182 Lists all of the bond-specific information (updelay, downdelay, time
 183 until the next rebalance) about the given bonded \fIport\fR, or all
 184 bonded ports if no \fIport\fR is given.  Also lists information about
 185 each slave: whether it is enabled or disabled, the time to completion
 186 of an updelay or downdelay if one is in progress, whether it is the
 187 active slave, the hashes assigned to the slave.  Any LACP information
 188 related to this bond may be found using the \fBlacp/show\fR command.
 189 .
 190 .IP "\fBbond/migrate\fR \fIport\fR \fIhash\fR \fIslave\fR"
 191 Only valid for SLB bonds.  Assigns a given MAC hash to a new slave.
 192 \fIport\fR specifies the bond port, \fIhash\fR the MAC hash to be
 193 migrated (as a decimal number between 0 and 255), and \fIslave\fR the
 194 new slave to be assigned.
 195 .IP
 196 The reassignment is not permanent: rebalancing or fail-over will
 197 cause the MAC hash to be shifted to a new slave in the usual
 198 manner.
 199 .IP
 200 A MAC hash cannot be migrated to a disabled slave.
 201 .IP "\fBbond/set\-active\-slave\fR \fIport\fR \fIslave\fR"
 202 Sets \fIslave\fR as the active slave on \fIport\fR.  \fIslave\fR must
 203 currently be enabled.
 204 .IP
 205 The setting is not permanent: a new active slave will be selected
 206 if \fIslave\fR becomes disabled.
 207 .IP "\fBbond/enable\-slave\fR \fIport\fR \fIslave\fR"
 208 .IQ "\fBbond/disable\-slave\fR \fIport\fR \fIslave\fR"
 209 Enables (or disables) \fIslave\fR on the given bond \fIport\fR, skipping any
 210 updelay (or downdelay).
 211 .IP
 212 This setting is not permanent: it persists only until the carrier
 213 status of \fIslave\fR changes.
 214 .IP "\fBbond/hash\fR \fImac\fR [\fIvlan\fR] [\fIbasis\fR]"
 215 Returns the hash value which would be used for \fImac\fR with \fIvlan\fR
 216 and \fIbasis\fR if specified.
 217 .
 218 .IP "\fBlacp/show\fR [\fIport\fR]"
 219 Lists all of the LACP related information about the given \fIport\fR:
 220 active or passive, aggregation key, system id, and system priority.  Also
 221 lists information about each slave: whether it is enabled or disabled,
 222 whether it is attached or detached, port id and priority, actor
 223 information, and partner information.  If \fIport\fR is not specified,
 224 then displays detailed information about all interfaces with CFM
 225 enabled.
 226 .SS "DPCTL DATAPATH DEBUGGING COMMANDS"
 227 The primary way to configure \fBovs\-vswitchd\fR is through the Open
 228 vSwitch database, e.g. using \fBovs\-vsctl\fR(8).  These commands
 229 provide a debugging interface for managing datapaths.  They implement
 230 the same features (and syntax) as \fBovs\-dpctl\fR(8).  Unlike
 231 \fBovs\-dpctl\fR(8), these commands work with datapaths that are
 232 integrated into \fBovs\-vswitchd\fR (e.g. the \fBnetdev\fR datapath
 233 type).
 234 .PP
 235 .
 236 .ds DX \fBdpctl/\fR
 237 .de DO
 238 \\$2 \\$1 \\$3
 239 ..
 240 .so lib/dpctl.man
 241 .
 242 .SS "DPIF-NETDEV COMMANDS"
 243 These commands are used to expose internal information (mostly statistics)
 244 about the ``dpif-netdev'' userspace datapath. If there is only one datapath
 245 (as is often the case, unless \fBdpctl/\fR commands are used), the \fIdp\fR
 246 argument can be omitted.
 247 .IP "\fBdpif-netdev/pmd-stats-show\fR [\fIdp\fR]"
 248 Shows performance statistics for each pmd thread of the datapath \fIdp\fR.
 249 The special thread ``main'' sums up the statistics of every non pmd thread.
 250 The sum of ``emc hits'', ``masked hits'' and ``miss'' is the number of
 251 packets received by the datapath.  Cycles are counted using the TSC or similar
 252 facilities (when available on the platform).  To reset these counters use
 253 \fBdpif-netdev/pmd-stats-clear\fR. The duration of one cycle depends on the
 254 measuring infrastructure.
 255 .IP "\fBdpif-netdev/pmd-stats-clear\fR [\fIdp\fR]"
 256 Resets to zero the per pmd thread performance numbers shown by the
 257 \fBdpif-netdev/pmd-stats-show\fR command.  It will NOT reset datapath or
 258 bridge statistics, only the values shown by the above command.
 259 .IP "\fBdpif-netdev/pmd-rxq-show\fR [\fIdp\fR]"
 260 For each pmd thread of the datapath \fIdp\fR shows list of queue-ids with
 261 port names, which this thread polls.
 262 .
 263 .so ofproto/ofproto-dpif-unixctl.man
 264 .so ofproto/ofproto-unixctl.man
 265 .so lib/vlog-unixctl.man
 266 .so lib/memory-unixctl.man
 267 .so lib/coverage-unixctl.man
 268 .so ofproto/ofproto-tnl-unixctl.man
 269 .
 270 .SH "OPENFLOW IMPLEMENTATION"
 271 .
 272 .PP
 273 This section documents aspects of OpenFlow for which the OpenFlow
 274 specification requires documentation.
 275 .
 276 .SS "Packet buffering."
 277 The OpenFlow specification, version 1.2, says:
 278 .
 279 .IP
 280 Switches that implement buffering are expected to expose, through
 281 documentation, both the amount of available buffering, and the length
 282 of time before buffers may be reused.
 283 .
 284 .PP
 285 Open vSwitch maintains a separate set of 256 packet buffers for each
 286 OpenFlow connection.  Any given packet buffer is preserved until it is
 287 referenced by an \fBOFPT_FLOW_MOD\fR or \fBOFPT_PACKET_OUT\fR request
 288 or for 5 seconds, whichever comes first.
 289 .
 290 .SH "LIMITS"
 291 .
 292 .PP
 293 We believe these limits to be accurate as of this writing.  These
 294 limits assume the use of the Linux kernel datapath.
 295 .
 296 .IP \(bu
 297 \fBovs\-vswitchd\fR started through \fBovs\-ctl\fR(8) provides a limit of 65535
 298 file descriptors.  The limits on the number of bridges and ports is decided by
 299 the availability of file descriptors.  With the Linux kernel datapath, creation
 300 of a single bridge consumes three file descriptors and adding a port consumes
 301 "n-handler-threads" file descriptors per bridge port.  Performance will degrade
 302 beyond 1,024 ports per bridge due to fixed hash table sizing.  Other platforms
 303 may have different limitations.
 304 .
 305 .IP \(bu
 306 2,048 MAC learning entries per bridge, by default.  (This is
 307 configurable via \fBother\-config:mac\-table\-size\fR in the
 308 \fBBridge\fR table.  See \fBovs\-vswitchd.conf.db\fR(5) for details.)
 309 .
 310 .IP \(bu
 311 Kernel flows are limited only by memory available to the kernel.
 312 Performance will degrade beyond 1,048,576 kernel flows per bridge with
 313 a 32-bit kernel, beyond 262,144 with a 64-bit kernel.
 314 (\fBovs\-vswitchd\fR should never install anywhere near that many
 315 flows.)
 316 .
 317 .IP \(bu
 318 OpenFlow flows are limited only by available memory.  Performance is
 319 linear in the number of unique wildcard patterns.  That is, an
 320 OpenFlow table that contains many flows that all match on the same
 321 fields in the same way has a constant-time lookup, but a table that
 322 contains many flows that match on different fields requires lookup
 323 time linear in the number of flows.
 324 .
 325 .IP \(bu
 326 255 ports per bridge participating in 802.1D Spanning Tree Protocol.
 327 .
 328 .IP \(bu
 329 32 mirrors per bridge.
 330 .
 331 .IP \(bu
 332 15 bytes for the name of a port.  (This is a Linux kernel limitation.)
 333 .
 334 .SH "SEE ALSO"
 335 .BR ovs\-appctl (8),
 336 .BR ovsdb\-server (1),
 337 \fBINSTALL.Linux\fR in the Open vSwitch distribution.