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 For details on initializing the \fBovs\-vswitchd\fR DPDK datapath,
  88 refer to INSTALL.DPDK.md or \fBovs\-vswitchd.conf.db\fR(5) for
  89 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-types\fR \fIinterface\fR"
 116 Queries the interface for a list of Quality of Service types that are
 117 configurable via Open vSwitch for the given \fIinterface\fR.
 118 .IP "\fBqos/show\fR \fIinterface\fR"
 119 Queries the kernel for Quality of Service configuration and statistics
 120 associated with the given \fIinterface\fR.
 121 .IP "\fBbfd/show\fR [\fIinterface\fR]"
 122 Displays detailed information about Bidirectional Forwarding Detection
 123 configured on \fIinterface\fR.  If \fIinterface\fR is not specified,
 124 then displays detailed information about all interfaces with BFD
 125 enabled.
 126 .IP "\fBbfd/set-forwarding\fR [\fIinterface\fR] \fIstatus\fR"
 127 Force the fault status of the BFD module on \fIinterface\fR (or all
 128 interfaces if none is given) to be \fIstatus\fR.  \fIstatus\fR can be
 129 "true", "false", or "normal" which reverts to the standard behavior.
 130 .IP "\fBcfm/show\fR [\fIinterface\fR]"
 131 Displays detailed information about Connectivity Fault Management
 132 configured on \fIinterface\fR.  If \fIinterface\fR is not specified,
 133 then displays detailed information about all interfaces with CFM
 134 enabled.
 135 .IP "\fBcfm/set-fault\fR [\fIinterface\fR] \fIstatus\fR"
 136 Force the fault status of the CFM module on \fIinterface\fR (or all
 137 interfaces if none is given) to be \fIstatus\fR.  \fIstatus\fR can be
 138 "true", "false", or "normal" which reverts to the standard behavior.
 139 .IP "\fBstp/tcn\fR [\fIbridge\fR]"
 140 Forces a topology change event on \fIbridge\fR if it's running STP.  This
 141 may cause it to send Topology Change Notifications to its peers and flush
 142 its MAC table..  If no \fIbridge\fR is given, forces a topology change
 143 event on all bridges.
 144 .SS "BRIDGE COMMANDS"
 145 These commands manage bridges.
 146 .IP "\fBfdb/flush\fR [\fIbridge\fR]"
 147 Flushes \fIbridge\fR MAC address learning table, or all learning tables
 148 if no \fIbridge\fR is given.
 149 .IP "\fBfdb/show\fR \fIbridge\fR"
 150 Lists each MAC address/VLAN pair learned by the specified \fIbridge\fR,
 151 along with the port on which it was learned and the age of the entry,
 152 in seconds.
 153 .IP "\fBmdb/flush\fR [\fIbridge\fR]"
 154 Flushes \fIbridge\fR multicast snooping table, or all snooping tables
 155 if no \fIbridge\fR is given.
 156 .IP "\fBmdb/show\fR \fIbridge\fR"
 157 Lists each multicast group/VLAN pair learned by the specified \fIbridge\fR,
 158 along with the port on which it was learned and the age of the entry,
 159 in seconds.
 160 .IP "\fBbridge/reconnect\fR [\fIbridge\fR]"
 161 Makes \fIbridge\fR drop all of its OpenFlow controller connections and
 162 reconnect.  If \fIbridge\fR is not specified, then all bridges drop
 163 their controller connections and reconnect.
 164 .IP
 165 This command might be useful for debugging OpenFlow controller issues.
 166 .
 167 .IP "\fBbridge/dump\-flows\fR \fIbridge\fR"
 168 Lists all flows in \fIbridge\fR, including those normally hidden to
 169 commands such as \fBovs\-ofctl dump\-flows\fR.  Flows set up by mechanisms
 170 such as in-band control and fail-open are hidden from the controller
 171 since it is not allowed to modify or override them.
 172 .SS "BOND COMMANDS"
 173 These commands manage bonded ports on an Open vSwitch's bridges.  To
 174 understand some of these commands, it is important to understand a
 175 detail of the bonding implementation called ``source load balancing''
 176 (SLB).  Instead of directly assigning Ethernet source addresses to
 177 slaves, the bonding implementation computes a function that maps an
 178 48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash''
 179 value).  All of the Ethernet addresses that map to a single 8-bit
 180 value are then assigned to a single slave.
 181 .IP "\fBbond/list\fR"
 182 Lists all of the bonds, and their slaves, on each bridge.
 183 .
 184 .IP "\fBbond/show\fR [\fIport\fR]"
 185 Lists all of the bond-specific information (updelay, downdelay, time
 186 until the next rebalance) about the given bonded \fIport\fR, or all
 187 bonded ports if no \fIport\fR is given.  Also lists information about
 188 each slave: whether it is enabled or disabled, the time to completion
 189 of an updelay or downdelay if one is in progress, whether it is the
 190 active slave, the hashes assigned to the slave.  Any LACP information
 191 related to this bond may be found using the \fBlacp/show\fR command.
 192 .
 193 .IP "\fBbond/migrate\fR \fIport\fR \fIhash\fR \fIslave\fR"
 194 Only valid for SLB bonds.  Assigns a given MAC hash to a new slave.
 195 \fIport\fR specifies the bond port, \fIhash\fR the MAC hash to be
 196 migrated (as a decimal number between 0 and 255), and \fIslave\fR the
 197 new slave to be assigned.
 198 .IP
 199 The reassignment is not permanent: rebalancing or fail-over will
 200 cause the MAC hash to be shifted to a new slave in the usual
 201 manner.
 202 .IP
 203 A MAC hash cannot be migrated to a disabled slave.
 204 .IP "\fBbond/set\-active\-slave\fR \fIport\fR \fIslave\fR"
 205 Sets \fIslave\fR as the active slave on \fIport\fR.  \fIslave\fR must
 206 currently be enabled.
 207 .IP
 208 The setting is not permanent: a new active slave will be selected
 209 if \fIslave\fR becomes disabled.
 210 .IP "\fBbond/enable\-slave\fR \fIport\fR \fIslave\fR"
 211 .IQ "\fBbond/disable\-slave\fR \fIport\fR \fIslave\fR"
 212 Enables (or disables) \fIslave\fR on the given bond \fIport\fR, skipping any
 213 updelay (or downdelay).
 214 .IP
 215 This setting is not permanent: it persists only until the carrier
 216 status of \fIslave\fR changes.
 217 .IP "\fBbond/hash\fR \fImac\fR [\fIvlan\fR] [\fIbasis\fR]"
 218 Returns the hash value which would be used for \fImac\fR with \fIvlan\fR
 219 and \fIbasis\fR if specified.
 220 .
 221 .IP "\fBlacp/show\fR [\fIport\fR]"
 222 Lists all of the LACP related information about the given \fIport\fR:
 223 active or passive, aggregation key, system id, and system priority.  Also
 224 lists information about each slave: whether it is enabled or disabled,
 225 whether it is attached or detached, port id and priority, actor
 226 information, and partner information.  If \fIport\fR is not specified,
 227 then displays detailed information about all interfaces with CFM
 228 enabled.
 229 .SS "DPCTL DATAPATH DEBUGGING COMMANDS"
 230 The primary way to configure \fBovs\-vswitchd\fR is through the Open
 231 vSwitch database, e.g. using \fBovs\-vsctl\fR(8).  These commands
 232 provide a debugging interface for managing datapaths.  They implement
 233 the same features (and syntax) as \fBovs\-dpctl\fR(8).  Unlike
 234 \fBovs\-dpctl\fR(8), these commands work with datapaths that are
 235 integrated into \fBovs\-vswitchd\fR (e.g. the \fBnetdev\fR datapath
 236 type).
 237 .PP
 238 .
 239 .ds DX \fBdpctl/\fR
 240 .de DO
 241 \\$2 \\$1 \\$3
 242 ..
 243 .so lib/dpctl.man
 244 .
 245 .SS "DPIF-NETDEV COMMANDS"
 246 These commands are used to expose internal information (mostly statistics)
 247 about the ``dpif-netdev'' userspace datapath. If there is only one datapath
 248 (as is often the case, unless \fBdpctl/\fR commands are used), the \fIdp\fR
 249 argument can be omitted.
 250 .IP "\fBdpif-netdev/pmd-stats-show\fR [\fIdp\fR]"
 251 Shows performance statistics for each pmd thread of the datapath \fIdp\fR.
 252 The special thread ``main'' sums up the statistics of every non pmd thread.
 253 The sum of ``emc hits'', ``masked hits'' and ``miss'' is the number of
 254 packets received by the datapath.  Cycles are counted using the TSC or similar
 255 facilities (when available on the platform).  To reset these counters use
 256 \fBdpif-netdev/pmd-stats-clear\fR. The duration of one cycle depends on the
 257 measuring infrastructure.
 258 .IP "\fBdpif-netdev/pmd-stats-clear\fR [\fIdp\fR]"
 259 Resets to zero the per pmd thread performance numbers shown by the
 260 \fBdpif-netdev/pmd-stats-show\fR command.  It will NOT reset datapath or
 261 bridge statistics, only the values shown by the above command.
 262 .IP "\fBdpif-netdev/pmd-rxq-show\fR [\fIdp\fR]"
 263 For each pmd thread of the datapath \fIdp\fR shows list of queue-ids with
 264 port names, which this thread polls.
 265 .
 266 .so ofproto/ofproto-dpif-unixctl.man
 267 .so ofproto/ofproto-unixctl.man
 268 .so lib/vlog-unixctl.man
 269 .so lib/memory-unixctl.man
 270 .so lib/coverage-unixctl.man
 271 .so ofproto/ofproto-tnl-unixctl.man
 272 .
 273 .SH "OPENFLOW IMPLEMENTATION"
 274 .
 275 .PP
 276 This section documents aspects of OpenFlow for which the OpenFlow
 277 specification requires documentation.
 278 .
 279 .SS "Packet buffering."
 280 The OpenFlow specification, version 1.2, says:
 281 .
 282 .IP
 283 Switches that implement buffering are expected to expose, through
 284 documentation, both the amount of available buffering, and the length
 285 of time before buffers may be reused.
 286 .
 287 .PP
 288 Open vSwitch maintains a separate set of 256 packet buffers for each
 289 OpenFlow connection.  Any given packet buffer is preserved until it is
 290 referenced by an \fBOFPT_FLOW_MOD\fR or \fBOFPT_PACKET_OUT\fR request
 291 or for 5 seconds, whichever comes first.
 292 .
 293 .SH "LIMITS"
 294 .
 295 .PP
 296 We believe these limits to be accurate as of this writing.  These
 297 limits assume the use of the Linux kernel datapath.
 298 .
 299 .IP \(bu
 300 \fBovs\-vswitchd\fR started through \fBovs\-ctl\fR(8) provides a limit of 65535
 301 file descriptors.  The limits on the number of bridges and ports is decided by
 302 the availability of file descriptors.  With the Linux kernel datapath, creation
 303 of a single bridge consumes three file descriptors and adding a port consumes
 304 "n-handler-threads" file descriptors per bridge port.  Performance will degrade
 305 beyond 1,024 ports per bridge due to fixed hash table sizing.  Other platforms
 306 may have different limitations.
 307 .
 308 .IP \(bu
 309 2,048 MAC learning entries per bridge, by default.  (This is
 310 configurable via \fBother\-config:mac\-table\-size\fR in the
 311 \fBBridge\fR table.  See \fBovs\-vswitchd.conf.db\fR(5) for details.)
 312 .
 313 .IP \(bu
 314 Kernel flows are limited only by memory available to the kernel.
 315 Performance will degrade beyond 1,048,576 kernel flows per bridge with
 316 a 32-bit kernel, beyond 262,144 with a 64-bit kernel.
 317 (\fBovs\-vswitchd\fR should never install anywhere near that many
 318 flows.)
 319 .
 320 .IP \(bu
 321 OpenFlow flows are limited only by available memory.  Performance is
 322 linear in the number of unique wildcard patterns.  That is, an
 323 OpenFlow table that contains many flows that all match on the same
 324 fields in the same way has a constant-time lookup, but a table that
 325 contains many flows that match on different fields requires lookup
 326 time linear in the number of flows.
 327 .
 328 .IP \(bu
 329 255 ports per bridge participating in 802.1D Spanning Tree Protocol.
 330 .
 331 .IP \(bu
 332 32 mirrors per bridge.
 333 .
 334 .IP \(bu
 335 15 bytes for the name of a port.  (This is a Linux kernel limitation.)
 336 .
 337 .SH "SEE ALSO"
 338 .BR ovs\-appctl (8),
 339 .BR ovsdb\-server (1),
 340 \fBINSTALL.Linux\fR in the Open vSwitch distribution.