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. database may be an OVSDB active or passive connection method, as described in ovsdb(7). The default is unix:@RUNDIR@/db.sock.

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, ovs-dpctl(8) (and its userspace datapath counterparts accessible via ovs-appctl dpctl/command) are not needed with ovs-vswitchd and should not be used because they can interfere with its operation. These tools are still useful for diagnostics.

An Open vSwitch datapath kernel module must be loaded for ovs-vswitchd to be useful. Refer to the documentation 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 on page faults (on allocation, when running on Linux kernel 4.4 or older), 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 ovs-vswitchd to use DPDK ports, refer to the documentation or ovs-vswitchd.conf.db(5).

  DPDK HW Access Options

--hw-rawio-access
    Tells ovs-vswitchd to retain the CAP_SYS_RAWIO capability, to allow userspace drivers access to raw hardware memory. This will also allow the ovs-vswitchd daemon to call iopl() and ioperm() functions as well as access memory devices to set port access. This is a very powerful capability, so generally only enable as needed for specific hardware (for example mlx5 with full hardware offload via rte_flow).

  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 --cleanup
    Causes ovs-vswitchd to gracefully terminate. If --cleanup is specified, deletes flows from datapaths and releases other datapath resources configured by ovs-vswitchd. Otherwise, datapath flows and other resources remains undeleted. Resources of datapaths that are integrated into ovs-vswitchd (e.g. the netdev datapath type) are always released regardless of --cleanup except for ports with internal type. Use --cleanup to release internal ports too.

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.

stp/show [bridge]
    Displays detailed information about spanning tree on the bridge. If bridge is not specified, then displays detailed information about all bridges with STP enabled.

rstp/tcn [bridge]
    Forces a topology change event on bridge if it's running RSTP. 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.

rstp/show [bridge]
    Displays detailed information about rapid spanning tree on the bridge. If bridge is not specified, then displays detailed information about all bridges with RSTP enabled.

  BRIDGE COMMANDS
These commands manage bridges.

fdb/add bridge port vlan mac
    Adds mac address to a port and vlan on a bridge. This utility can be used to pre-populate fdb table without relying on dynamic mac learning.

fdb/del bridge vlan mac
    Deletes mac address from a port and vlan on a bridge.

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.

fdb/stats-clear [bridge]
    Clear bridge MAC address learning table statistics, or all statistics if no bridge is given.

fdb/stats-show bridge
    Show MAC address learning table statistics for the specified bridge.

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 [--offload-stats] 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. If --offload-stats are specified then also list statistics for offloaded packets and bytes, which are a subset of the total packets and bytes.

  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 members, 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 member.

bond/list
    Lists all of the bonds, and their members, 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 members: 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 member, the hashes assigned to the member. Any LACP information related to this bond may be found using the lacp/show command.

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

    The reassignment is not permanent: rebalancing or fail-over will cause the MAC hash to be shifted to a new member in the usual manner.

    A MAC hash cannot be migrated to a disabled member.

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

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

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

    This setting is not permanent: it persists only until the carrier status of member 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 member: 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.

lacp/stats-show [port]
    Lists various stats about LACP PDUs (number of RX/TX PDUs, bad PDUs received) and member state (number of times its state expired/defaulted and carrier status changed) for the given port. If port is not specified, then displays stats of all interfaces with LACP 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).

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 does not maintains any packet buffers.

  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 default idle bundle lifetime of 10 seconds. (This is configurable via other-config:bundle-idle-timeout in the Open_vSwitch table. See ovs-vswitchd.conf.db(5) for details.)

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 each port consumes one additional file descriptor. Other platforms may have different limitations.

•   8,192 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, for ports implemented in the Linux kernel. Ports implemented in userspace, such as patch ports, do not have an arbitrary length limitation. OpenFlow also limit port names to 15 bytes.

SEE ALSO
ovs-appctl(8), ovsdb-server(1).