ovs-vswitchd(8)

NAME
ovs-vswitchd - Open vSwitch daemon

SYNOPSIS
ovs-vswitchd [database]

DESCRIPTION
A daemon that manages and controls any number of Open vSwitch switches on the local machine.

The database argument specifies how ovs-vswitchd connects to ovsdb-server. The default is unix:@RUNDIR@/db.sock. The following forms are accepted:

ovs-vswitchd retrieves its configuration from database at startup. It sets up Open vSwitch datapaths and then operates switching across each bridge described in its configuration files. As the database changes, ovs-vswitchd automatically updates its configuration to match.

ovs-vswitchd switches may be configured with any of the following features:

•   L2 switching with MAC learning.

•   NIC bonding with automatic fail-over and source MAC-based TX load balancing ("SLB").

•   802.1Q VLAN support.

•   Port mirroring, with optional VLAN tagging.

•   NetFlow v5 flow logging.

•   sFlow(R) monitoring.

•   Connectivity to an external OpenFlow controller, such as NOX.

Only a single instance of ovs-vswitchd is intended to run at a time. A single ovs-vswitchd can manage any number of switch instances, up to the maximum number of supported Open vSwitch datapaths.

ovs-vswitchd does all the necessary management of Open vSwitch datapaths itself. Thus, external tools, such ovs-dpctl(8), are not needed for managing datapaths in conjunction with ovs-vswitchd, and their use to modify datapaths when ovs-vswitchd is running can interfere with its operation. (ovs-dpctl may still be useful for diagnostics.)

An Open vSwitch datapath kernel module must be loaded for ovs-vswitchd to be useful. Please refer to the INSTALL.Linux file included in the Open vSwitch distribution for instructions on how to build and load the Open vSwitch kernel module.

OPTIONS

--mlockall
    Causes ovs-vswitchd to call the mlockall() 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.

    Some systems do not support mlockall() at all, and other systems only allow privileged users, such as the superuser, to use it. ovs-vswitchd emits a log message if mlockall() is unavailable or unsuccessful.

  DPDK Options
For details on initializing the ovs-vswitchd DPDK datapath, refer to INSTALL.DPDK.md or ovs-vswitchd.conf.db(5) for details.

  Daemon Options

  Service Options

  Public Key Infrastructure Options

  Logging Options

  Other Options

RUNTIME MANAGEMENT COMMANDS
ovs-appctl(8) can send commands to a running ovs-vswitchd process. The currently supported commands are described below. The command descriptions assume an understanding of how to configure Open vSwitch.

  GENERAL COMMANDS

exit
    Causes ovs-vswitchd to gracefully terminate.

qos/show-types interface
    Queries the interface for a list of Quality of Service types that are configurable via Open vSwitch for the given interface.

qos/show interface
    Queries the kernel for Quality of Service configuration and statistics associated with the given interface.

bfd/show [interface]
    Displays detailed information about Bidirectional Forwarding Detection configured on interface. If interface is not specified, then displays detailed information about all interfaces with BFD enabled.

bfd/set-forwarding [interface] status
    Force the fault status of the BFD module on interface (or all interfaces if none is given) to be status. status can be "true", "false", or "normal" which reverts to the standard behavior.

cfm/show [interface]
    Displays detailed information about Connectivity Fault Management configured on interface. If interface is not specified, then displays detailed information about all interfaces with CFM enabled.

cfm/set-fault [interface] status
    Force the fault status of the CFM module on interface (or all interfaces if none is given) to be status. status can be "true", "false", or "normal" which reverts to the standard behavior.

stp/tcn [bridge]
    Forces a topology change event on bridge if it's running STP. This may cause it to send Topology Change Notifications to its peers and flush its MAC table.. If no bridge is given, forces a topology change event on all bridges.

  BRIDGE COMMANDS
These commands manage bridges.

fdb/flush [bridge]
    Flushes bridge MAC address learning table, or all learning tables if no bridge is given.

fdb/show bridge
    Lists each MAC address/VLAN pair learned by the specified bridge, along with the port on which it was learned and the age of the entry, in seconds.

mdb/flush [bridge]
    Flushes bridge multicast snooping table, or all snooping tables if no bridge is given.

mdb/show bridge
    Lists each multicast group/VLAN pair learned by the specified bridge, along with the port on which it was learned and the age of the entry, in seconds.

bridge/reconnect [bridge]
    Makes bridge drop all of its OpenFlow controller connections and reconnect. If bridge is not specified, then all bridges drop their controller connections and reconnect.

    This command might be useful for debugging OpenFlow controller issues.

bridge/dump-flows bridge
    Lists all flows in bridge, including those normally hidden to commands such as ovs-ofctl dump-flows. 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.

  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.

bond/list
    Lists all of the bonds, and their slaves, on each bridge.

bond/show [port]
    Lists all of the bond-specific information (updelay, downdelay, time until the next rebalance) about the given bonded port, or all bonded ports if no port 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 lacp/show command.

bond/migrate port hash slave
    Only valid for SLB bonds. Assigns a given MAC hash to a new slave. port specifies the bond port, hash the MAC hash to be migrated (as a decimal number between 0 and 255), and slave the new slave to be assigned.

    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.

    A MAC hash cannot be migrated to a disabled slave.

bond/set-active-slave port slave
    Sets slave as the active slave on port. slave must currently be enabled.

    The setting is not permanent: a new active slave will be selected if slave becomes disabled.

bond/enable-slave port slave
    Enables (or disables) slave on the given bond port, skipping any updelay (or downdelay).

    This setting is not permanent: it persists only until the carrier status of slave changes.

bond/hash mac [vlan] [basis]
    Returns the hash value which would be used for mac with vlan and basis if specified.

lacp/show [port]
    Lists all of the LACP related information about the given port: 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 port is not specified, then displays detailed information about all interfaces with CFM enabled.

  DPCTL DATAPATH DEBUGGING COMMANDS
The primary way to configure ovs-vswitchd is through the Open vSwitch database, e.g. using ovs-vsctl(8). These commands provide a debugging interface for managing datapaths. They implement the same features (and syntax) as ovs-dpctl(8). Unlike ovs-dpctl(8), these commands work with datapaths that are integrated into ovs-vswitchd (e.g. the netdev datapath type).

  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 dpctl/ commands are used), the dp argument can be omitted.

dpif-netdev/pmd-stats-show [dp]
    Shows performance statistics for each pmd thread of the datapath dp. 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 dpif-netdev/pmd-stats-clear. The duration of one cycle depends on the measuring infrastructure.

dpif-netdev/pmd-stats-clear [dp]
    Resets to zero the per pmd thread performance numbers shown by the dpif-netdev/pmd-stats-show command. It will NOT reset datapath or bridge statistics, only the values shown by the above command.

dpif-netdev/pmd-rxq-show [dp]
    For each pmd thread of the datapath dp shows list of queue-ids with port names, which this thread polls.

OPENFLOW IMPLEMENTATION

This section documents aspects of OpenFlow for which the OpenFlow specification requires documentation.

  Packet buffering.
The OpenFlow specification, version 1.2, says:

    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.

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 OFPT_FLOW_MOD or OFPT_PACKET_OUT request or for 5 seconds, whichever comes first.

  Bundle lifetime
The OpenFlow specification, version 1.4, says:

    If the switch does not receive any OFPT_BUNDLE_CONTROL or OFPT_BUNDLE_ADD_MESSAGE message for an opened bundle_id for a switch defined time greater than 1s, it may send an ofp_error_msg with OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code. If the switch does not receive any new message in a bundle apart from echo request and replies for a switch defined time greater than 1s, it may send an ofp_error_msg with OFPET_BUNDLE_FAILED type and OFPBFC_TIMEOUT code.

Open vSwitch implements idle bundle lifetime of 10 seconds.

LIMITS

We believe these limits to be accurate as of this writing. These limits assume the use of the Linux kernel datapath.

•   ovs-vswitchd started through ovs-ctl(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.

•   2,048 MAC learning entries per bridge, by default. (This is configurable via other-config:mac-table-size in the Bridge table. See ovs-vswitchd.conf.db(5) for details.)

•   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. (ovs-vswitchd should never install anywhere near that many flows.)

•   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.

•   255 ports per bridge participating in 802.1D Spanning Tree Protocol.

•   32 mirrors per bridge.

•   15 bytes for the name of a port. (This is a Linux kernel limitation.)

SEE ALSO
ovs-appctl(8), ovsdb-server(1), INSTALL.Linux in the Open vSwitch distribution.