| ovs-vswitchd.conf.db(5) | Open vSwitch Manual | ovs-vswitchd.conf.db(5) |
ovs-vswitchd.conf.db - Open_vSwitch database schema
A database with this schema holds the configuration for one Open vSwitch daemon. The top-level configuration for the daemon is the Open_vSwitch table, which must have exactly one record. Records in other tables are significant only when they can be reached directly or indirectly from the Open_vSwitch table. Records that are not reachable from the Open_vSwitch table are automatically deleted from the database, except for records in a few distinguished ``root set’’ tables.
Most tables contain two special columns, named other_config and external_ids. These columns have the same form and purpose each place that they appear, so we describe them here to save space later.
The following list summarizes the purpose of each of the tables in the Open_vSwitch database. Each table is described in more detail on a later page.
Configuration for an Open vSwitch daemon. There must be exactly one record in the Open_vSwitch table.
The statistics column contains key-value pairs that report statistics about a system running an Open vSwitch. These are updated periodically (currently, every 5 seconds). Key-value pairs that cannot be determined or that do not apply to a platform are omitted.
These columns report the types and versions of the hardware and software running Open vSwitch. We recommend in general that software should test whether specific features are supported instead of relying on version number checks. These values are primarily intended for reporting to human administrators.
These columns report capabilities of the Open vSwitch instance.
These columns primarily configure the Open vSwitch database (ovsdb-server), not the Open vSwitch switch (ovs-vswitchd). The OVSDB database also uses the ssl settings.
The Open vSwitch switch does read the database configuration to determine remote IP addresses to which in-band control should apply.
These settings control the global configuration of IPsec tunnels. The options column of the Interface table configures IPsec for individual tunnels.
OVS IPsec supports the following three forms of authentication. Currently, all IPsec tunnels must use the same form:
When an IPsec tunnel is configured in this database, multiple independent components take responsibility for implementing it. ovs-vswitchd and its datapath handle packet forwarding to the tunnel and a separate daemon pushes the tunnel’s IPsec policy configuration to the kernel or other entity that implements it. There is a race: if the former configuration completes before the latter, then packets sent by the local host over the tunnel can be transmitted in plaintext. Using this setting, OVS users can avoid this undesirable situation.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Configuration for a bridge within an Open_vSwitch.
A Bridge record represents an Ethernet switch with one or more ``ports,’’ which are the Port records pointed to by the Bridge’s ports column.
The IEEE 802.1D Spanning Tree Protocol (STP) is a network protocol that ensures loop-free topologies. It allows redundant links to be included in the network to provide automatic backup paths if the active links fails.
These settings configure the slower-to-converge but still widely supported version of Spanning Tree Protocol, sometimes known as 802.1D-1998. Open vSwitch also supports the newer Rapid Spanning Tree Protocol (RSTP), documented later in the section titled Rapid Spanning Tree Configuration.
These key-value pairs report the status of 802.1D-1998. They are present only if STP is enabled (via the stp_enable column).
Rapid Spanning Tree Protocol (RSTP), like STP, is a network protocol that ensures loop-free topologies. RSTP superseded STP with the publication of 802.1D-2004. Compared to STP, RSTP converges more quickly and recovers more quickly from failures.
These key-value pairs report the status of 802.1D-2004. They are present only if RSTP is enabled (via the rstp_enable column).
Multicast snooping (RFC 4541) monitors the Internet Group Management Protocol (IGMP) and Multicast Listener Discovery traffic between hosts and multicast routers. The switch uses what IGMP and MLD snooping learns to forward multicast traffic only to interfaces that are connected to interested receivers. Currently it supports IGMPv1, IGMPv2, IGMPv3, MLDv1 and MLDv2 protocols.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A port within a Bridge.
Most commonly, a port has exactly one ``interface,’’ pointed to by its interfaces column. Such a port logically corresponds to a port on a physical Ethernet switch. A port with more than one interface is a ``bonded port’’ (see Bonding Configuration).
Some properties that one might think as belonging to a port are actually part of the port’s Interface members.
In short, a VLAN (short for ``virtual LAN’’) is a way to partition a single switch into multiple switches. VLANs can be confusing, so for an introduction, please refer to the question ``What’s a VLAN?’’ in the Open vSwitch FAQ.
A VLAN is sometimes encoded into a packet using a 802.1Q or 802.1ad VLAN header, but every packet is part of some VLAN whether or not it is encoded in the packet. (A packet that appears to have no VLAN is part of VLAN 0, by default.) As a result, it’s useful to think of a VLAN as a metadata property of a packet, separate from how the VLAN is encoded. For a given port, this column determines how the encoding of a packet that ingresses or egresses the port maps to the packet’s VLAN. When a packet enters the switch, its VLAN is determined based on its setting in this column and its VLAN headers, if any, and then, conceptually, the VLAN headers are then stripped off. Conversely, when a packet exits the switch, its VLAN and the settings in this column determine what VLAN headers, if any, are pushed onto the packet before it egresses the port.
The VLAN configuration in this column affects Open vSwitch only when it is doing ``normal switching.’’ It does not affect flows set up by an OpenFlow controller, outside of the OpenFlow ``normal action.’’
Bridge ports support the following types of VLAN configuration:
A packet will only egress through bridge ports that carry the VLAN of the packet, as described by the rules above.
A port that has more than one interface is a ``bonded port.’’ Bonding allows for load balancing and fail-over.
The following types of bonding will work with any kind of upstream switch. On the upstream switch, do not configure the interfaces as a bond:
The following modes require the upstream switch to support 802.3ad with successful LACP negotiation. If LACP negotiation fails and other-config:lacp-fallback-ab is true, then active-backup mode is used:
These columns apply only to bonded ports. Their values are otherwise ignored.
An important part of link bonding is detecting that links are down so that they may be disabled. These settings determine how Open vSwitch detects link failure.
LACP, the Link Aggregation Control Protocol, is an IEEE standard that allows switches to automatically detect that they are connected by multiple links and aggregate across those links. These settings control LACP behavior.
These settings control behavior when a bond is in balance-slb or balance-tcp mode.
The configuration here is only meaningful, and the status is only populated, when 802.1D-1998 Spanning Tree Protocol is enabled on the port’s Bridge with its stp_enable column.
The configuration here is only meaningful, and the status and statistics are only populated, when 802.1D-1998 Spanning Tree Protocol is enabled on the port’s Bridge with its stp_enable column.
Key-value pairs that report port statistics. The update period is controlled by other_config:stats-update-interval in the Open_vSwitch table.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
An interface within a Port.
When a client adds a new interface, Open vSwitch chooses an OpenFlow port number for the new port. If the client that adds the port fills in ofport_request, then Open vSwitch tries to use its value as the OpenFlow port number. Otherwise, or if the requested port number is already in use or cannot be used for another reason, Open vSwitch automatically assigns a free port number. Regardless of how the port number was obtained, Open vSwitch then reports in ofport the port number actually assigned.
Open vSwitch limits the port numbers that it automatically assigns to the range 1 through 32,767, inclusive. Controllers therefore have free use of ports 32,768 and up.
These options apply to interfaces with type of geneve, bareudp, gre, ip6gre, vxlan, lisp and stt.
Each tunnel must be uniquely identified by the combination of type, options:remote_ip, options:local_ip, and options:in_key. If two ports are defined that are the same except one has an optional identifier and the other does not, the more specific one is matched first. options:in_key is considered more specific than options:local_ip if a port defines one and another port defines the other. options:in_key is not applicable for bareudp tunnels. Hence it is not considered while identifying a bareudp tunnel.
gre interfaces support these options.
gre, ip6gre, geneve, bareudp and vxlan interfaces support these options.
Setting any of these options enables IPsec support for a given tunnel. gre, geneve, vxlan and stt interfaces support these options. See the IPsec section in the Open_vSwitch table for a description of each mode.
Only erspan interfaces support these options.
These options apply only to patch ports, that is, interfaces whose type column is patch. Patch ports are mainly a way to connect otherwise independent bridges to one another, similar to how one might plug an Ethernet cable (a ``patch cable’’) into two physical switches to connect those switches. The effect of plugging a patch port into two switches is conceptually similar to that of plugging the two ends of a Linux veth device into those switches, but the implementation of patch ports makes them much more efficient.
Patch ports may connect two different bridges (the usual case) or the same bridge. In the latter case, take special care to avoid loops, e.g. by programming appropriate flows with OpenFlow. Patch ports do not work if its ends are attached to bridges on different datapaths, e.g. to connect bridges in system and netdev datapaths.
The following command creates and connects patch ports p0 and p1 and adds them to bridges br0 and br1, respectively:
ovs-vsctl add-port br0 p0 -- set Interface p0 type=patch options:peer=p1 \
-- add-port br1 p1 -- set Interface p1 type=patch options:peer=p0
Only PMD netdevs support these options.
These settings controls behaviour of EMC lookups/insertions for packets received from the interface.
The MTU (maximum transmission unit) is the largest amount of data that can fit into a single Ethernet frame. The standard Ethernet MTU is 1500 bytes. Some physical media and many kinds of virtual interfaces can be configured with higher MTUs.
A client may change an interface MTU by filling in mtu_request. Open vSwitch then reports in mtu the currently configured value.
Status information about interfaces attached to bridges, updated every 5 seconds. Not all interfaces have all of these properties; virtual interfaces don’t have a link speed, for example. Non-applicable columns will have empty values.
DPDK specific interface status options.
Key-value pairs that report interface statistics. The current implementation updates these counters periodically. The update period is controlled by other_config:stats-update-interval in the Open_vSwitch table. Future implementations may update them when an interface is created, when they are queried (e.g. using an OVSDB select operation), and just before an interface is deleted due to virtual interface hot-unplug or VM shutdown, and perhaps at other times, but not on any regular periodic basis.
These are the same statistics reported by OpenFlow in its struct ofp_port_stats structure. If an interface does not support a given statistic, then that pair is omitted.
These settings control ingress policing for packets received on this interface. On a physical interface, this limits the rate at which traffic is allowed into the system from the outside; on a virtual interface (one connected to a virtual machine), this limits the rate at which the VM is able to transmit.
Policing is a simple form of quality-of-service that simply drops packets received in excess of the configured rate. Due to its simplicity, policing is usually less accurate and less effective than egress QoS (which is configured using the QoS and Queue tables).
Policing is currently implemented on Linux and OVS with DPDK. Both implementations use a simple ``token bucket’’ approach:
Policing interacts badly with some network protocols, and especially with fragmented IP packets. Suppose that there is enough network activity to keep the bucket nearly empty all the time. Then this token bucket algorithm will forward a single packet every so often, with the period depending on packet size and on the configured rate. All of the fragments of an IP packets are normally transmitted back-to-back, as a group. In such a situation, therefore, only one of these fragments will be forwarded and the rest will be dropped. IP does not provide any way for the intended recipient to ask for only the remaining fragments. In such a case there are two likely possibilities for what will happen next: either all of the fragments will eventually be retransmitted (as TCP will do), in which case the same problem will recur, or the sender will not realize that its packet has been dropped and data will simply be lost (as some UDP-based protocols will do). Either way, it is possible that no forward progress will ever occur.
BFD, defined in RFC 5880 and RFC 5881, allows point-to-point detection of connectivity failures by occasional transmission of BFD control messages. Open vSwitch implements BFD to serve as a more popular and standards compliant alternative to CFM.
BFD operates by regularly transmitting BFD control messages at a rate negotiated independently in each direction. Each endpoint specifies the rate at which it expects to receive control messages, and the rate at which it is willing to transmit them. By default, Open vSwitch uses a detection multiplier of three, meaning that an endpoint signals a connectivity fault if three consecutive BFD control messages fail to arrive. In the case of a unidirectional connectivity issue, the system not receiving BFD control messages signals the problem to its peer in the messages it transmits.
The Open vSwitch implementation of BFD aims to comply faithfully with RFC 5880 requirements. Open vSwitch does not implement the optional Authentication or ``Echo Mode’’ features.
OVS 2.13 and earlier intercepted and processed all BFD packets. OVS 2.14 and later only intercept and process BFD packets destined to a configured BFD instance, and other BFD packets are made available to the OVS flow table for forwarding.
A controller sets up key-value pairs in the bfd column to enable and configure BFD.
The switch sets key-value pairs in the bfd_status column to report the status of BFD on this interface. When BFD is not enabled, with bfd:enable, the switch clears all key-value pairs from bfd_status.
802.1ag Connectivity Fault Management (CFM) allows a group of Maintenance Points (MPs) called a Maintenance Association (MA) to detect connectivity problems with each other. MPs within a MA should have complete and exclusive interconnectivity. This is verified by occasionally broadcasting Continuity Check Messages (CCMs) at a configurable transmission interval.
According to the 802.1ag specification, each Maintenance Point should be configured out-of-band with a list of Remote Maintenance Points it should have connectivity to. Open vSwitch differs from the specification in this area. It simply assumes the link is faulted if no Remote Maintenance Points are reachable, and considers it not faulted otherwise.
When operating over tunnels which have no in_key, or an in_key of flow. CFM will only accept CCMs with a tunnel key of zero.
These key-value pairs specifically apply to an interface that represents a virtual Ethernet interface connected to a virtual machine. These key-value pairs should not be present for other types of interfaces. Keys whose names end in -uuid have values that uniquely identify the entity in question. For a Citrix XenServer hypervisor, these values are UUIDs in RFC 4122 format. Other hypervisors may use other formats.
Auto Attach configuration for a particular interface.
Ethernet flow control defined in IEEE 802.1Qbb provides link level flow control using MAC pause frames. Implemented only for interfaces with type dpdk.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Configuration for a particular OpenFlow table.
Open vSwitch supports limiting the number of flows that may be installed in a flow table, via the flow_limit column. When adding a flow would exceed this limit, by default Open vSwitch reports an error, but there are two ways to configure Open vSwitch to instead delete (``evict’’) a flow to make room for the new one:
When a flow must be evicted due to overflow, the flow to evict is chosen through an approximation of the following algorithm. This algorithm is used regardless of how eviction was enabled:
The eviction process only considers flows that have an idle timeout or a hard timeout. That is, eviction never deletes permanent flows. (Permanent flows do count against flow_limit.)
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Quality of Service (QoS) configuration for each Port that references it.
The linux-htb and linux-hfsc classes support the following key-value pair:
QoS type egress-policer provides egress policing for userspace port types with DPDK. It has the following key-value pairs defined.
The linux-sfq QoS supports the following key-value pairs:
The linux-netem QoS supports the following key-value pairs:
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A configuration for a port output queue, used in configuring Quality of Service (QoS) features. May be referenced by queues column in QoS table.
QoS type linux-htb may use queue_ids less than 61440. It has the following key-value pairs defined.
QoS type linux-hfsc may use queue_ids less than 61440. It has the following key-value pairs defined.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A port mirror within a Bridge.
A port mirror configures a bridge to send selected frames to special ``mirrored’’ ports, in addition to their normal destinations. Mirroring traffic may also be referred to as SPAN or RSPAN, depending on how the mirrored traffic is sent.
When a packet enters an Open vSwitch bridge, it becomes eligible for mirroring based on its ingress port and VLAN. As the packet travels through the flow tables, each time it is output to a port, it becomes eligible for mirroring based on the egress port and VLAN. In Open vSwitch 2.5 and later, mirroring occurs just after a packet first becomes eligible, using the packet as it exists at that point; in Open vSwitch 2.4 and earlier, mirroring occurs only after a packet has traversed all the flow tables, using the original packet as it entered the bridge. This makes a difference only when the flow table modifies the packet: in Open vSwitch 2.4, the modifications are never visible to mirrors, whereas in Open vSwitch 2.5 and later modifications made before the first output that makes it eligible for mirroring to a particular destination are visible.
A packet that enters an Open vSwitch bridge is mirrored to a particular destination only once, even if it is eligible for multiple reasons. For example, a packet would be mirrored to a particular output_port only once, even if it is selected for mirroring to that port by select_dst_port and select_src_port in the same or different Mirror records.
To be selected for mirroring, a given packet must enter or leave the bridge through a selected port and it must also be in one of the selected VLANs.
These columns are mutually exclusive. Exactly one of them must be nonempty.
Key-value pairs that report mirror statistics. The update period is controlled by other_config:stats-update-interval in the Open_vSwitch table.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
An OpenFlow controller.
OpenFlow switches send certain messages to controllers spontanenously, that is, not in response to any request from the controller. These messages are called ``asynchronous messages.’’ These columns allow asynchronous messages to be limited or disabled to ensure the best use of network resources.
A switch can forward packets to a controller over the OpenFlow protocol. Forwarding packets this way at too high a rate can overwhelm a controller, frustrate use of the OpenFlow connection for other purposes, increase the latency of flow setup, and use an unreasonable amount of bandwidth. Therefore, Open vSwitch supports limiting the rate of packet forwarding to a controller.
There are two main reasons in OpenFlow for a packet to be sent to a controller: either the packet ``misses’’ in the flow table, that is, there is no matching flow, or a flow table action says to send the packet to the controller. Open vSwitch limits the rate of each kind of packet separately at the configured rate. Therefore, the actual rate that packets are sent to the controller can be up to twice the configured rate, when packets are sent for both reasons.
This feature is specific to forwarding packets over an OpenFlow connection. It is not general-purpose QoS. See the QoS table for quality of service configuration, and ingress_policing_rate in the Interface table for ingress policing configuration.
These values report the effects of rate limiting. Their values are relative to establishment of the most recent OpenFlow connection, or since rate limiting was enabled, whichever happened more recently. Each consists of two values, one with TYPE replaced by miss for rate limiting flow table misses, and the other with TYPE replaced by action for rate limiting packets sent by OpenFlow actions.
These statistics are reported only when controller rate limiting is enabled.
These values are considered only in in-band control mode (see connection_mode).
When multiple controllers are configured on a single bridge, there should be only one set of unique values in these columns. If different values are set for these columns in different controllers, the effect is unspecified.
Additional configuration for a connection between the controller and the Open vSwitch.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Configuration for a database connection to an Open vSwitch database (OVSDB) client.
This table primarily configures the Open vSwitch database (ovsdb-server), not the Open vSwitch switch (ovs-vswitchd). The switch does read the table to determine what connections should be treated as in-band.
The Open vSwitch database server can initiate and maintain active connections to remote clients. It can also listen for database connections.
Key-value pair of is_connected is always updated. Other key-value pairs in the status columns may be updated depends on the target type.
When target specifies a connection method that listens for inbound connections (e.g. ptcp: or punix:), both n_connections and is_connected may also be updated while the remaining key-value pairs are omitted.
On the other hand, when target specifies an outbound connection, all key-value pairs may be updated, except the above-mentioned two key-value pairs associated with inbound connection targets. They are omitted.
Additional configuration for a connection between the manager and the Open vSwitch Database.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A NetFlow target. NetFlow is a protocol that exports a number of details about terminating IP flows, such as the principals involved and duration.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Configuration for a datapath within Open_vSwitch.
A datapath is responsible for providing the packet handling in Open vSwitch. There are two primary datapath implementations used by Open vSwitch: kernel and userspace. Kernel datapath implementations are available for Linux and Hyper-V, and selected as system in the datapath_type column of the Bridge table. The userspace datapath is used by DPDK and AF-XDP, and is selected as netdev in the datapath_type column of the Bridge table.
A datapath of a particular type is shared by all the bridges that use that datapath. Thus, configurations applied to this table affect all bridges that use this datapath.
The capabilities column reports a datapath’s features. For the netdev datapath, the capabilities are fixed for a given version of Open vSwitch because this datapath is built into the ovs-vswitchd binary. The Linux kernel and Windows and other datapaths, which are external to OVS userspace, can vary in version and capabilities independently from ovs-vswitchd.
Some of these features indicate whether higher-level Open vSwitch features are available. For example, OpenFlow features for connection-tracking are available only when capabilities:ct_state is true. A controller that wishes to determine whether a feature is supported could, therefore, consult the relevant capabilities in this table. However, as a general rule, it is better for a controller to try to use the higher-level feature and use the result as an indication of support, since the low-level capabilities are more likely to shift over time than the high-level features that rely on them.
These capabilities are granular because Open vSwitch and its datapaths added support for connection tracking over several releases, with features added individually over that time.
When Open vSwitch translates actions from OpenFlow into the datapath representation, some of the datapath actions may modify the packet or have other side effects that later datapath actions can’t undo. The OpenFlow ct, meter, output with truncation, encap, decap, and dec_nsh_ttl actions fall into this category. Often, this is not a problem because nothing later on needs the original packet.
Such actions can, however, occur in circumstances where the translation does require the original packet. For example, an OpenFlow output action might direct a packet to a patch port, which might in turn lead to a ct action that NATs the packet (which cannot be undone), and then afterward when control flow pops back across the patch port some other action might need to act on the original packet.
Open vSwitch has two different ways to implement this ``save and restore’’ via datapath actions. These capabilities indicate which one Open vSwitch will choose. When neither is available, Open vSwitch simply fails in situations that require this feature.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Connection tracking zone configuration
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Connection tracking timeout policy configuration
The overall purpose of these columns is described under Common Columns at the beginning of this document.
SSL configuration for an Open_vSwitch.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A set of sFlow(R) targets. sFlow is a protocol for remote monitoring of switches.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Configuration for sending packets to IPFIX collectors.
IPFIX is a protocol that exports a number of details about flows. The IPFIX implementation in Open vSwitch samples packets at a configurable rate, extracts flow information from those packets, optionally caches and aggregates the flow information, and sends the result to one or more collectors.
IPFIX in Open vSwitch can be configured two different ways:
These values affect only per-bridge sampling. See above for a description of the differences between per-bridge and flow-based sampling.
The overall purpose of these columns is described under Common Columns at the beginning of this document.
A set of IPFIX collectors of packet samples generated by OpenFlow sample actions. This table is used only for IPFIX flow-based sampling, not for per-bridge sampling (see the IPFIX table for a description of the two forms).
The overall purpose of these columns is described under Common Columns at the beginning of this document.
Auto Attach configuration within a bridge. The IETF Auto-Attach SPBM draft standard describes a compact method of using IEEE 802.1AB Link Layer Discovery Protocol (LLDP) together with a IEEE 802.1aq Shortest Path Bridging (SPB) network to automatically attach network devices to individual services in a SPB network. The intent here is to allow network applications and devices using OVS to be able to easily take advantage of features offered by industry standard SPB networks.
Auto Attach (AA) uses LLDP to communicate between a directly connected Auto Attach Client (AAC) and Auto Attach Server (AAS). The LLDP protocol is extended to add two new Type-Length-Value tuples (TLVs). The first new TLV supports the ongoing discovery of directly connected AA correspondents. Auto Attach operates by regularly transmitting AA discovery TLVs between the AA client and AA server. By exchanging these discovery messages, both the AAC and AAS learn the system name and system description of their peer. In the OVS context, OVS operates as the AA client and the AA server resides on a switch at the edge of the SPB network.
Once AA discovery has been completed the AAC then uses the second new TLV to deliver identifier mappings from the AAC to the AAS. A primary feature of Auto Attach is to facilitate the mapping of VLANs defined outside the SPB network onto service ids (ISIDs) defined within the SPM network. By doing so individual external VLANs can be mapped onto specific SPB network services. These VLAN id to ISID mappings can be configured and managed locally using new options added to the ovs-vsctl command.
The Auto Attach OVS feature does not provide a full implementation of the LLDP protocol. Support for the mandatory TLVs as defined by the LLDP standard and support for the AA TLV extensions is provided. LLDP protocol support in OVS can be enabled or disabled on a port by port basis. LLDP support is disabled by default.
| DB Schema 8.2.0 | Open vSwitch 2.15.0 |