335 lines
13 KiB
Groff
Executable File
335 lines
13 KiB
Groff
Executable File
.\" -*- nroff -*-
|
|
.de IQ
|
|
. br
|
|
. ns
|
|
. IP "\\$1"
|
|
..
|
|
.TH ovs\-vswitchd 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual"
|
|
.\" This program's name:
|
|
.ds PN ovs\-vswitchd
|
|
.
|
|
.SH NAME
|
|
ovs\-vswitchd \- Open vSwitch daemon
|
|
.
|
|
.SH SYNOPSIS
|
|
\fBovs\-vswitchd \fR[\fIdatabase\fR]
|
|
.
|
|
.SH DESCRIPTION
|
|
A daemon that manages and controls any number of Open vSwitch switches
|
|
on the local machine.
|
|
.PP
|
|
The \fIdatabase\fR argument specifies how \fBovs\-vswitchd\fR connects
|
|
to \fBovsdb\-server\fR. The default is \fBunix:@RUNDIR@/db.sock\fR.
|
|
The following forms are accepted:
|
|
.so ovsdb/remote-active.man
|
|
.so ovsdb/remote-passive.man
|
|
.PP
|
|
\fBovs\-vswitchd\fR retrieves its configuration from \fIdatabase\fR at
|
|
startup. It sets up Open vSwitch datapaths and then operates
|
|
switching across each bridge described in its configuration files. As
|
|
the database changes, \fBovs\-vswitchd\fR automatically updates its
|
|
configuration to match.
|
|
.PP
|
|
\fBovs\-vswitchd\fR switches may be configured with any of the following
|
|
features:
|
|
.
|
|
.IP \(bu
|
|
L2 switching with MAC learning.
|
|
.
|
|
.IP \(bu
|
|
NIC bonding with automatic fail-over and source MAC-based TX load
|
|
balancing ("SLB").
|
|
.
|
|
.IP \(bu
|
|
802.1Q VLAN support.
|
|
.
|
|
.IP \(bu
|
|
Port mirroring, with optional VLAN tagging.
|
|
.
|
|
.IP \(bu
|
|
NetFlow v5 flow logging.
|
|
.
|
|
.IP \(bu
|
|
sFlow(R) monitoring.
|
|
.
|
|
.IP \(bu
|
|
Connectivity to an external OpenFlow controller, such as NOX.
|
|
.
|
|
.PP
|
|
Only a single instance of \fBovs\-vswitchd\fR is intended to run at a time.
|
|
A single \fBovs\-vswitchd\fR can manage any number of switch instances, up
|
|
to the maximum number of supported Open vSwitch datapaths.
|
|
.PP
|
|
\fBovs\-vswitchd\fR does all the necessary management of Open vSwitch datapaths
|
|
itself. Thus, external tools, such \fBovs\-dpctl\fR(8), are not needed for
|
|
managing datapaths in conjunction with \fBovs\-vswitchd\fR, and their use
|
|
to modify datapaths when \fBovs\-vswitchd\fR is running can interfere with
|
|
its operation. (\fBovs\-dpctl\fR may still be useful for diagnostics.)
|
|
.PP
|
|
An Open vSwitch datapath kernel module must be loaded for \fBovs\-vswitchd\fR
|
|
to be useful. Please refer to the \fBINSTALL.Linux\fR file included in the
|
|
Open vSwitch distribution for instructions on how to build and load
|
|
the Open vSwitch kernel module.
|
|
.PP
|
|
.SH OPTIONS
|
|
.IP "\fB\-\-mlockall\fR"
|
|
Causes \fBovs\-vswitchd\fR to call the \fBmlockall()\fR function, to
|
|
attempt to lock all of its process memory into physical RAM,
|
|
preventing the kernel from paging any of its memory to disk. This
|
|
helps to avoid networking interruptions due to system memory pressure.
|
|
.IP
|
|
Some systems do not support \fBmlockall()\fR at all, and other systems
|
|
only allow privileged users, such as the superuser, to use it.
|
|
\fBovs\-vswitchd\fR emits a log message if \fBmlockall()\fR is
|
|
unavailable or unsuccessful.
|
|
.
|
|
.SS "DPDK Options"
|
|
.IP "\fB\-\-dpdk\fR"
|
|
Initialize \fBovs\-vswitchd\fR DPDK datapath. Refer to INSTALL.DPDK
|
|
for details.
|
|
.SS "Daemon Options"
|
|
.ds DD \
|
|
\fBovs\-vswitchd\fR detaches only after it has connected to the \
|
|
database, retrieved the initial configuration, and set up that \
|
|
configuration.
|
|
.so lib/daemon.man
|
|
.SS "Service Options"
|
|
.so lib/service.man
|
|
.SS "Public Key Infrastructure Options"
|
|
.so lib/ssl.man
|
|
.so lib/ssl-bootstrap.man
|
|
.SS "Logging Options"
|
|
.so lib/vlog.man
|
|
.SS "Other Options"
|
|
.so lib/unixctl.man
|
|
.so lib/common.man
|
|
.
|
|
.SH "RUNTIME MANAGEMENT COMMANDS"
|
|
\fBovs\-appctl\fR(8) can send commands to a running
|
|
\fBovs\-vswitchd\fR process. The currently supported commands are
|
|
described below. The command descriptions assume an understanding of
|
|
how to configure Open vSwitch.
|
|
.SS "GENERAL COMMANDS"
|
|
.IP "\fBexit\fR"
|
|
Causes \fBovs\-vswitchd\fR to gracefully terminate.
|
|
.IP "\fBqos/show\fR \fIinterface\fR"
|
|
Queries the kernel for Quality of Service configuration and statistics
|
|
associated with the given \fIinterface\fR.
|
|
.IP "\fBbfd/show\fR [\fIinterface\fR]"
|
|
Displays detailed information about Bidirectional Forwarding Detection
|
|
configured on \fIinterface\fR. If \fIinterface\fR is not specified,
|
|
then displays detailed information about all interfaces with BFD
|
|
enabled.
|
|
.IP "\fBbfd/set-forwarding\fR [\fIinterface\fR] \fIstatus\fR"
|
|
Force the fault status of the BFD module on \fIinterface\fR (or all
|
|
interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be
|
|
"true", "false", or "normal" which reverts to the standard behavior.
|
|
.IP "\fBcfm/show\fR [\fIinterface\fR]"
|
|
Displays detailed information about Connectivity Fault Management
|
|
configured on \fIinterface\fR. If \fIinterface\fR is not specified,
|
|
then displays detailed information about all interfaces with CFM
|
|
enabled.
|
|
.IP "\fBcfm/set-fault\fR [\fIinterface\fR] \fIstatus\fR"
|
|
Force the fault status of the CFM module on \fIinterface\fR (or all
|
|
interfaces if none is given) to be \fIstatus\fR. \fIstatus\fR can be
|
|
"true", "false", or "normal" which reverts to the standard behavior.
|
|
.IP "\fBstp/tcn\fR [\fIbridge\fR]"
|
|
Forces a topology change event on \fIbridge\fR if it's running STP. This
|
|
may cause it to send Topology Change Notifications to its peers and flush
|
|
its MAC table.. If no \fIbridge\fR is given, forces a topology change
|
|
event on all bridges.
|
|
.SS "BRIDGE COMMANDS"
|
|
These commands manage bridges.
|
|
.IP "\fBfdb/flush\fR [\fIbridge\fR]"
|
|
Flushes \fIbridge\fR MAC address learning table, or all learning tables
|
|
if no \fIbridge\fR is given.
|
|
.IP "\fBfdb/show\fR \fIbridge\fR"
|
|
Lists each MAC address/VLAN pair learned by the specified \fIbridge\fR,
|
|
along with the port on which it was learned and the age of the entry,
|
|
in seconds.
|
|
.IP "\fBmdb/flush\fR [\fIbridge\fR]"
|
|
Flushes \fIbridge\fR multicast snooping table, or all snooping tables
|
|
if no \fIbridge\fR is given.
|
|
.IP "\fBmdb/show\fR \fIbridge\fR"
|
|
Lists each multicast group/VLAN pair learned by the specified \fIbridge\fR,
|
|
along with the port on which it was learned and the age of the entry,
|
|
in seconds.
|
|
.IP "\fBbridge/reconnect\fR [\fIbridge\fR]"
|
|
Makes \fIbridge\fR drop all of its OpenFlow controller connections and
|
|
reconnect. If \fIbridge\fR is not specified, then all bridges drop
|
|
their controller connections and reconnect.
|
|
.IP
|
|
This command might be useful for debugging OpenFlow controller issues.
|
|
.
|
|
.IP "\fBbridge/dump\-flows\fR \fIbridge\fR"
|
|
Lists all flows in \fIbridge\fR, including those normally hidden to
|
|
commands such as \fBovs\-ofctl dump\-flows\fR. Flows set up by mechanisms
|
|
such as in-band control and fail-open are hidden from the controller
|
|
since it is not allowed to modify or override them.
|
|
.SS "BOND COMMANDS"
|
|
These commands manage bonded ports on an Open vSwitch's bridges. To
|
|
understand some of these commands, it is important to understand a
|
|
detail of the bonding implementation called ``source load balancing''
|
|
(SLB). Instead of directly assigning Ethernet source addresses to
|
|
slaves, the bonding implementation computes a function that maps an
|
|
48-bit Ethernet source addresses into an 8-bit value (a ``MAC hash''
|
|
value). All of the Ethernet addresses that map to a single 8-bit
|
|
value are then assigned to a single slave.
|
|
.IP "\fBbond/list\fR"
|
|
Lists all of the bonds, and their slaves, on each bridge.
|
|
.
|
|
.IP "\fBbond/show\fR [\fIport\fR]"
|
|
Lists all of the bond-specific information (updelay, downdelay, time
|
|
until the next rebalance) about the given bonded \fIport\fR, or all
|
|
bonded ports if no \fIport\fR is given. Also lists information about
|
|
each slave: whether it is enabled or disabled, the time to completion
|
|
of an updelay or downdelay if one is in progress, whether it is the
|
|
active slave, the hashes assigned to the slave. Any LACP information
|
|
related to this bond may be found using the \fBlacp/show\fR command.
|
|
.
|
|
.IP "\fBbond/migrate\fR \fIport\fR \fIhash\fR \fIslave\fR"
|
|
Only valid for SLB bonds. Assigns a given MAC hash to a new slave.
|
|
\fIport\fR specifies the bond port, \fIhash\fR the MAC hash to be
|
|
migrated (as a decimal number between 0 and 255), and \fIslave\fR the
|
|
new slave to be assigned.
|
|
.IP
|
|
The reassignment is not permanent: rebalancing or fail-over will
|
|
cause the MAC hash to be shifted to a new slave in the usual
|
|
manner.
|
|
.IP
|
|
A MAC hash cannot be migrated to a disabled slave.
|
|
.IP "\fBbond/set\-active\-slave\fR \fIport\fR \fIslave\fR"
|
|
Sets \fIslave\fR as the active slave on \fIport\fR. \fIslave\fR must
|
|
currently be enabled.
|
|
.IP
|
|
The setting is not permanent: a new active slave will be selected
|
|
if \fIslave\fR becomes disabled.
|
|
.IP "\fBbond/enable\-slave\fR \fIport\fR \fIslave\fR"
|
|
.IQ "\fBbond/disable\-slave\fR \fIport\fR \fIslave\fR"
|
|
Enables (or disables) \fIslave\fR on the given bond \fIport\fR, skipping any
|
|
updelay (or downdelay).
|
|
.IP
|
|
This setting is not permanent: it persists only until the carrier
|
|
status of \fIslave\fR changes.
|
|
.IP "\fBbond/hash\fR \fImac\fR [\fIvlan\fR] [\fIbasis\fR]"
|
|
Returns the hash value which would be used for \fImac\fR with \fIvlan\fR
|
|
and \fIbasis\fR if specified.
|
|
.
|
|
.IP "\fBlacp/show\fR [\fIport\fR]"
|
|
Lists all of the LACP related information about the given \fIport\fR:
|
|
active or passive, aggregation key, system id, and system priority. Also
|
|
lists information about each slave: whether it is enabled or disabled,
|
|
whether it is attached or detached, port id and priority, actor
|
|
information, and partner information. If \fIport\fR is not specified,
|
|
then displays detailed information about all interfaces with CFM
|
|
enabled.
|
|
.SS "DPCTL DATAPATH DEBUGGING COMMANDS"
|
|
The primary way to configure \fBovs\-vswitchd\fR is through the Open
|
|
vSwitch database, e.g. using \fBovs\-vsctl\fR(8). These commands
|
|
provide a debugging interface for managing datapaths. They implement
|
|
the same features (and syntax) as \fBovs\-dpctl\fR(8). Unlike
|
|
\fBovs\-dpctl\fR(8), these commands work with datapaths that are
|
|
integrated into \fBovs\-vswitchd\fR (e.g. the \fBnetdev\fR datapath
|
|
type).
|
|
.PP
|
|
.
|
|
.ds DX \fBdpctl/\fR
|
|
.de DO
|
|
\\$2 \\$1 \\$3
|
|
..
|
|
.so lib/dpctl.man
|
|
.
|
|
.SS "DPIF-NETDEV COMMANDS"
|
|
These commands are used to expose internal information (mostly statistics)
|
|
about the ``dpif-netdev'' userspace datapath. If there is only one datapath
|
|
(as is often the case, unless \fBdpctl/\fR commands are used), the \fIdp\fR
|
|
argument can be omitted.
|
|
.IP "\fBdpif-netdev/pmd-stats-show\fR [\fIdp\fR]"
|
|
Shows performance statistics for each pmd thread of the datapath \fIdp\fR.
|
|
The special thread ``main'' sums up the statistics of every non pmd thread.
|
|
The sum of ``emc hits'', ``masked hits'' and ``miss'' is the number of
|
|
packets received by the datapath. Cycles are counted using the TSC or similar
|
|
facilities (when available on the platform). To reset these counters use
|
|
\fBdpif-netdev/pmd-stats-clear\fR. The duration of one cycle depends on the
|
|
measuring infrastructure.
|
|
.IP "\fBdpif-netdev/pmd-stats-clear\fR [\fIdp\fR]"
|
|
Resets to zero the per pmd thread performance numbers shown by the
|
|
\fBdpif-netdev/pmd-stats-show\fR command. It will NOT reset datapath or
|
|
bridge statistics, only the values shown by the above command.
|
|
.
|
|
.so ofproto/ofproto-dpif-unixctl.man
|
|
.so ofproto/ofproto-unixctl.man
|
|
.so lib/vlog-unixctl.man
|
|
.so lib/memory-unixctl.man
|
|
.so lib/coverage-unixctl.man
|
|
.so ofproto/ofproto-tnl-unixctl.man
|
|
.
|
|
.SH "OPENFLOW IMPLEMENTATION"
|
|
.
|
|
.PP
|
|
This section documents aspects of OpenFlow for which the OpenFlow
|
|
specification requires documentation.
|
|
.
|
|
.SS "Packet buffering."
|
|
The OpenFlow specification, version 1.2, says:
|
|
.
|
|
.IP
|
|
Switches that implement buffering are expected to expose, through
|
|
documentation, both the amount of available buffering, and the length
|
|
of time before buffers may be reused.
|
|
.
|
|
.PP
|
|
Open vSwitch maintains a separate set of 256 packet buffers for each
|
|
OpenFlow connection. Any given packet buffer is preserved until it is
|
|
referenced by an \fBOFPT_FLOW_MOD\fR or \fBOFPT_PACKET_OUT\fR request
|
|
or for 5 seconds, whichever comes first.
|
|
.
|
|
.SH "LIMITS"
|
|
.
|
|
.PP
|
|
We believe these limits to be accurate as of this writing. These
|
|
limits assume the use of the Linux kernel datapath.
|
|
.
|
|
.IP \(bu
|
|
\fBovs\-vswitchd\fR started through \fBovs\-ctl\fR(8) provides a limit of 65535
|
|
file descriptors. The limits on the number of bridges and ports is decided by
|
|
the availability of file descriptors. With the Linux kernel datapath, creation
|
|
of a single bridge consumes three file descriptors and adding a port consumes
|
|
"n-handler-threads" file descriptors per bridge port. Performance will degrade
|
|
beyond 1,024 ports per bridge due to fixed hash table sizing. Other platforms
|
|
may have different limitations.
|
|
.
|
|
.IP \(bu
|
|
2,048 MAC learning entries per bridge, by default. (This is
|
|
configurable via \fBother\-config:mac\-table\-size\fR in the
|
|
\fBBridge\fR table. See \fBovs\-vswitchd.conf.db\fR(5) for details.)
|
|
.
|
|
.IP \(bu
|
|
Kernel flows are limited only by memory available to the kernel.
|
|
Performance will degrade beyond 1,048,576 kernel flows per bridge with
|
|
a 32-bit kernel, beyond 262,144 with a 64-bit kernel.
|
|
(\fBovs\-vswitchd\fR should never install anywhere near that many
|
|
flows.)
|
|
.
|
|
.IP \(bu
|
|
OpenFlow flows are limited only by available memory. Performance is
|
|
linear in the number of unique wildcard patterns. That is, an
|
|
OpenFlow table that contains many flows that all match on the same
|
|
fields in the same way has a constant-time lookup, but a table that
|
|
contains many flows that match on different fields requires lookup
|
|
time linear in the number of flows.
|
|
.
|
|
.IP \(bu
|
|
255 ports per bridge participating in 802.1D Spanning Tree Protocol.
|
|
.
|
|
.IP \(bu
|
|
32 mirrors per bridge.
|
|
.
|
|
.IP \(bu
|
|
15 bytes for the name of a port. (This is a Linux kernel limitation.)
|
|
.
|
|
.SH "SEE ALSO"
|
|
.BR ovs\-appctl (8),
|
|
.BR ovsdb\-server (1),
|
|
\fBINSTALL.Linux\fR in the Open vSwitch distribution.
|