+ <column name="fake_bridge">
+ Does this port represent a sub-bridge for its tagged VLAN within the
+ Bridge? See ovs-vsctl(8) for more information.
+ </column>
+
+ <column name="external_ids" key="fake-bridge-id-*">
+ External IDs for a fake bridge (see the <ref column="fake_bridge"/>
+ column) are defined by prefixing a <ref table="Bridge"/> <ref
+ table="Bridge" column="external_ids"/> key with
+ <code>fake-bridge-</code>,
+ e.g. <code>fake-bridge-xs-network-uuids</code>.
+ </column>
+ </group>
+
+ <group title="Port Status">
+ <p>
+ Status information about ports attached to bridges.
+ </p>
+ <column name="status">
+ Key-value pairs that report port status.
+ </column>
+ <column name="status" key="stp_port_id">
+ <p>
+ The port-id (in hex) used in spanning tree advertisements for
+ this port. Configuring the port-id is described in the
+ <code>stp-port-num</code> and <code>stp-port-priority</code>
+ keys of the <code>other_config</code> section earlier.
+ </p>
+ </column>
+ <column name="status" key="stp_state"
+ type='{"type": "string", "enum": ["set",
+ ["disabled", "listening", "learning",
+ "forwarding", "blocking"]]}'>
+ <p>
+ STP state of the port.
+ </p>
+ </column>
+ <column name="status" key="stp_sec_in_state"
+ type='{"type": "integer", "minInteger": 0}'>
+ <p>
+ The amount of time (in seconds) port has been in the current
+ STP state.
+ </p>
+ </column>
+ <column name="status" key="stp_role"
+ type='{"type": "string", "enum": ["set",
+ ["root", "designated", "alternate"]]}'>
+ <p>
+ STP role of the port.
+ </p>
+ </column>
+ </group>
+
+ <group title="Port Statistics">
+ <p>
+ Key-value pairs that report port statistics.
+ </p>
+ <group title="Statistics: STP transmit and receive counters">
+ <column name="statistics" key="stp_tx_count">
+ Number of STP BPDUs sent on this port by the spanning
+ tree library.
+ </column>
+ <column name="statistics" key="stp_rx_count">
+ Number of STP BPDUs received on this port and accepted by the
+ spanning tree library.
+ </column>
+ <column name="statistics" key="stp_error_count">
+ Number of bad STP BPDUs received on this port. Bad BPDUs
+ include runt packets and those with an unexpected protocol ID.
+ </column>
+ </group>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Interface" title="One physical network device in a Port.">
+ An interface within a <ref table="Port"/>.
+
+ <group title="Core Features">
+ <column name="name">
+ Interface name. Should be alphanumeric and no more than about 8 bytes
+ long. May be the same as the port name, for non-bonded ports. Must
+ otherwise be unique among the names of ports, interfaces, and bridges
+ on a host.
+ </column>
+
+ <column name="mac">
+ <p>Ethernet address to set for this interface. If unset then the
+ default MAC address is used:</p>
+ <ul>
+ <li>For the local interface, the default is the lowest-numbered MAC
+ address among the other bridge ports, either the value of the
+ <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
+ if set, or its actual MAC (for bonded ports, the MAC of its slave
+ whose name is first in alphabetical order). Internal ports and
+ bridge ports that are used as port mirroring destinations (see the
+ <ref table="Mirror"/> table) are ignored.</li>
+ <li>For other internal interfaces, the default MAC is randomly
+ generated.</li>
+ <li>External interfaces typically have a MAC address associated with
+ their hardware.</li>
+ </ul>
+ <p>Some interfaces may not have a software-controllable MAC
+ address.</p>
+ </column>
+
+ <column name="ofport">
+ <p>OpenFlow port number for this interface. Unlike most columns, this
+ column's value should be set only by Open vSwitch itself. Other
+ clients should set this column to an empty set (the default) when
+ creating an <ref table="Interface"/>.</p>
+ <p>Open vSwitch populates this column when the port number becomes
+ known. If the interface is successfully added,
+ <ref column="ofport"/> will be set to a number between 1 and 65535
+ (generally either in the range 1 to 65279, inclusive, or 65534, the
+ port number for the OpenFlow ``local port''). If the interface
+ cannot be added then Open vSwitch sets this column
+ to -1.</p>
+ </column>
+ </group>
+
+ <group title="System-Specific Details">
+ <column name="type">
+ <p>
+ The interface type, one of:
+ </p>
+
+ <dl>
+ <dt><code>system</code></dt>
+ <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
+ Sometimes referred to as ``external interfaces'' since they are
+ generally connected to hardware external to that on which the Open
+ vSwitch is running. The empty string is a synonym for
+ <code>system</code>.</dd>
+
+ <dt><code>internal</code></dt>
+ <dd>A simulated network device that sends and receives traffic. An
+ internal interface whose <ref column="name"/> is the same as its
+ bridge's <ref table="Open_vSwitch" column="name"/> is called the
+ ``local interface.'' It does not make sense to bond an internal
+ interface, so the terms ``port'' and ``interface'' are often used
+ imprecisely for internal interfaces.</dd>
+
+ <dt><code>tap</code></dt>
+ <dd>A TUN/TAP device managed by Open vSwitch.</dd>
+
+ <dt><code>gre</code></dt>
+ <dd>
+ An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
+ tunnel. See <ref group="Tunnel Options"/> for information on
+ configuring GRE tunnels.
+ </dd>
+
+ <dt><code>ipsec_gre</code></dt>
+ <dd>
+ An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
+ IPsec tunnel.
+ </dd>
+
+ <dt><code>capwap</code></dt>
+ <dd>
+ An Ethernet tunnel over the UDP transport portion of CAPWAP (RFC
+ 5415). This allows interoperability with certain switches that do
+ not support GRE. Only the tunneling component of the protocol is
+ implemented. UDP ports 58881 and 58882 are used as the source and
+ destination ports respectively. CAPWAP is currently supported only
+ with the Linux kernel datapath with kernel version 2.6.26 or later.
+ </dd>
+
+ <dt><code>patch</code></dt>
+ <dd>
+ A pair of virtual devices that act as a patch cable.
+ </dd>
+
+ <dt><code>null</code></dt>
+ <dd>An ignored interface.</dd>
+ </dl>
+ </column>
+ </group>
+
+ <group title="Tunnel Options">
+ <p>
+ These options apply to interfaces with <ref column="type"/> of
+ <code>gre</code>, <code>ipsec_gre</code>, and <code>capwap</code>.
+ </p>
+
+ <p>
+ Each tunnel must be uniquely identified by the combination of <ref
+ column="type"/>, <ref column="options" key="remote_ip"/>, <ref
+ column="options" key="local_ip"/>, and <ref column="options"
+ key="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. <ref column="options" key="in_key"/> is
+ considered more specific than <ref column="options" key="local_ip"/> if
+ a port defines one and another port defines the other.
+ </p>
+
+ <column name="options" key="remote_ip">
+ <p>
+ Required. The tunnel endpoint. Unicast and multicast endpoints are
+ both supported.
+ </p>
+
+ <p>
+ When a multicast endpoint is specified, a routing table lookup occurs
+ only when the tunnel is created. Following a routing change, delete
+ and then re-create the tunnel to force a new routing table lookup.
+ </p>
+ </column>
+
+ <column name="options" key="local_ip">
+ Optional. The destination IP that received packets must match.
+ Default is to match all addresses. Must be omitted when <ref
+ column="options" key="remote_ip"/> is a multicast address.
+ </column>
+
+ <column name="options" key="in_key">
+ <p>Optional. The key that received packets must contain, one of:</p>
+
+ <ul>
+ <li>
+ <code>0</code>. The tunnel receives packets with no key or with a
+ key of 0. This is equivalent to specifying no <ref column="options"
+ key="in_key"/> at all.
+ </li>
+ <li>
+ A positive 32-bit (for GRE) or 64-bit (for CAPWAP) number. The
+ tunnel receives only packets with the specified key.
+ </li>
+ <li>
+ The word <code>flow</code>. The tunnel accepts packets with any
+ key. The key will be placed in the <code>tun_id</code> field for
+ matching in the flow table. The <code>ovs-ofctl</code> manual page
+ contains additional information about matching fields in OpenFlow
+ flows.
+ </li>
+ </ul>
+
+ <p>
+ </p>
+ </column>
+
+ <column name="options" key="out_key">
+ <p>Optional. The key to be set on outgoing packets, one of:</p>
+
+ <ul>
+ <li>
+ <code>0</code>. Packets sent through the tunnel will have no key.
+ This is equivalent to specifying no <ref column="options"
+ key="out_key"/> at all.
+ </li>
+ <li>
+ A positive 32-bit (for GRE) or 64-bit (for CAPWAP) number. Packets
+ sent through the tunnel will have the specified key.
+ </li>
+ <li>
+ The word <code>flow</code>. Packets sent through the tunnel will
+ have the key set using the <code>set_tunnel</code> Nicira OpenFlow
+ vendor extension (0 is used in the absence of an action). The
+ <code>ovs-ofctl</code> manual page contains additional information
+ about the Nicira OpenFlow vendor extensions.
+ </li>
+ </ul>
+ </column>
+
+ <column name="options" key="key">
+ Optional. Shorthand to set <code>in_key</code> and
+ <code>out_key</code> at the same time.
+ </column>
+
+ <column name="options" key="tos">
+ Optional. The value of the ToS bits to be set on the encapsulating
+ packet. It may also be the word <code>inherit</code>, in which case
+ the ToS will be copied from the inner packet if it is IPv4 or IPv6
+ (otherwise it will be 0). The ECN fields are always inherited.
+ Default is 0.
+ </column>
+
+ <column name="options" key="ttl">
+ Optional. The TTL to be set on the encapsulating packet. It may also
+ be the word <code>inherit</code>, in which case the TTL will be copied
+ from the inner packet if it is IPv4 or IPv6 (otherwise it will be the
+ system default, typically 64). Default is the system default TTL.
+ </column>
+
+ <column name="options" key="df_inherit" type='{"type": "boolean"}'>
+ Optional. If enabled, the Don't Fragment bit will be copied from the
+ inner IP headers (those of the encapsulated traffic) to the outer
+ (tunnel) headers. Default is disabled; set to <code>true</code> to
+ enable.
+ </column>
+
+ <column name="options" key="df_default"
+ type='{"type": "boolean"}'>
+ Optional. If enabled, the Don't Fragment bit will be set by default on
+ tunnel headers if the <code>df_inherit</code> option is not set, or if
+ the encapsulated packet is not IP. Default is enabled; set to
+ <code>false</code> to disable.
+ </column>
+
+ <column name="options" key="pmtud" type='{"type": "boolean"}'>
+ Optional. Enable tunnel path MTU discovery. If enabled ``ICMP
+ Destination Unreachable - Fragmentation Needed'' messages will be
+ generated for IPv4 packets with the DF bit set and IPv6 packets above
+ the minimum MTU if the packet size exceeds the path MTU minus the size
+ of the tunnel headers. Note that this option causes behavior that is
+ typically reserved for routers and therefore is not entirely in
+ compliance with the IEEE 802.1D specification for bridges. Default is
+ enabled; set to <code>false</code> to disable.
+ </column>
+
+ <group title="Tunnel Options: gre only">
+ <p>
+ Only <code>gre</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="header_cache" type='{"type": "boolean"}'>
+ Enable caching of tunnel headers and the output path. This can lead
+ to a significant performance increase without changing behavior. In
+ general it should not be necessary to adjust this setting. However,
+ the caching can bypass certain components of the IP stack (such as
+ <code>iptables</code>) and it may be useful to disable it if these
+ features are required or as a debugging measure. Default is enabled,
+ set to <code>false</code> to disable.
+ </column>
+ </group>
+
+ <group title="Tunnel Options: gre and ipsec_gre only">
+ <p>
+ Only <code>gre</code> and <code>ipsec_gre</code> interfaces support
+ these options.
+ </p>
+
+ <column name="options" key="csum" type='{"type": "boolean"}'>
+ <p>
+ Optional. Compute GRE checksums on outgoing packets. Default is
+ disabled, set to <code>true</code> to enable. Checksums present on
+ incoming packets will be validated regardless of this setting.
+ </p>
+
+ <p>
+ GRE checksums impose a significant performance penalty because they
+ cover the entire packet. The encapsulated L3, L4, and L7 packet
+ contents typically have their own checksums, so this additional
+ checksum only adds value for the GRE and encapsulated L2 headers.
+ </p>
+
+ <p>
+ This option is supported for <code>ipsec_gre</code>, but not useful
+ because GRE checksums are weaker than, and redundant with, IPsec
+ payload authentication.
+ </p>
+ </column>
+ </group>
+
+ <group title="Tunnel Options: ipsec_gre only">
+ <p>
+ Only <code>ipsec_gre</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer_cert">
+ Required for certificate authentication. A string containing the
+ peer's certificate in PEM format. Additionally the host's
+ certificate must be specified with the <code>certificate</code>
+ option.
+ </column>
+
+ <column name="options" key="certificate">
+ Required for certificate authentication. The name of a PEM file
+ containing a certificate that will be presented to the peer during
+ authentication.
+ </column>
+
+ <column name="options" key="private_key">
+ Optional for certificate authentication. The name of a PEM file
+ containing the private key associated with <code>certificate</code>.
+ If <code>certificate</code> contains the private key, this option may
+ be omitted.
+ </column>
+
+ <column name="options" key="psk">
+ Required for pre-shared key authentication. Specifies a pre-shared
+ key for authentication that must be identical on both sides of the
+ tunnel.
+ </column>
+ </group>
+ </group>
+
+ <group title="Patch Options">
+ <p>
+ Only <code>patch</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer">
+ The <ref column="name"/> of the <ref table="Interface"/> for the other
+ side of the patch. The named <ref table="Interface"/>'s own
+ <code>peer</code> option must specify this <ref table="Interface"/>'s
+ name. That is, the two patch interfaces must have reversed <ref
+ column="name"/> and <code>peer</code> values.
+ </column>
+ </group>
+
+ <group title="Interface Status">
+ <p>
+ 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.
+ </p>
+ <column name="admin_state">
+ <p>
+ The administrative state of the physical network link.
+ </p>
+ </column>
+
+ <column name="link_state">
+ <p>
+ The observed state of the physical network link. This is ordinarily
+ the link's carrier status. If the interface's <ref table="Port"/> is
+ a bond configured for miimon monitoring, it is instead the network
+ link's miimon status.
+ </p>
+ </column>
+
+ <column name="link_resets">
+ <p>
+ The number of times Open vSwitch has observed the
+ <ref column="link_state"/> of this <ref table="Interface"/> change.
+ </p>
+ </column>
+
+ <column name="link_speed">
+ <p>
+ The negotiated speed of the physical network link.
+ Valid values are positive integers greater than 0.
+ </p>
+ </column>
+
+ <column name="duplex">
+ <p>
+ The duplex mode of the physical network link.
+ </p>
+ </column>
+
+ <column name="mtu">
+ <p>
+ The MTU (maximum transmission unit); i.e. 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.
+ </p>
+ <p>
+ This column will be empty for an interface that does not
+ have an MTU as, for example, some kinds of tunnels do not.
+ </p>
+ </column>
+
+ <column name="lacp_current">
+ Boolean value indicating LACP status for this interface. If true, this
+ interface has current LACP information about its LACP partner. This
+ information may be used to monitor the health of interfaces in a LACP
+ enabled port. This column will be empty if LACP is not enabled.
+ </column>
+
+ <column name="status">
+ Key-value pairs that report port status. Supported status values are
+ <ref column="type"/>-dependent; some interfaces may not have a valid
+ <ref column="status" key="driver_name"/>, for example.
+ </column>
+
+ <column name="status" key="driver_name">
+ The name of the device driver controlling the network adapter.
+ </column>
+
+ <column name="status" key="driver_version">
+ The version string of the device driver controlling the network
+ adapter.
+ </column>
+
+ <column name="status" key="firmware_version">
+ The version string of the network adapter's firmware, if available.
+ </column>
+
+ <column name="status" key="source_ip">
+ The source IP address used for an IPv4 tunnel end-point, such as
+ <code>gre</code> or <code>capwap</code>.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface">
+ Egress interface for tunnels. Currently only relevant for GRE and
+ CAPWAP tunnels. On Linux systems, this column will show the name of
+ the interface which is responsible for routing traffic destined for the
+ configured <ref column="options" key="remote_ip"/>. This could be an
+ internal interface such as a bridge port.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface_carrier"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ Whether carrier is detected on <ref column="status"
+ key="tunnel_egress_iface"/>.
+ </column>
+ </group>
+
+ <group title="Statistics">
+ <p>
+ Key-value pairs that report interface statistics. The current
+ implementation updates these counters periodically. Future
+ implementations may update them when an interface is created, when they
+ are queried (e.g. using an OVSDB <code>select</code> 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.
+ </p>
+ <p>
+ These are the same statistics reported by OpenFlow in its <code>struct
+ ofp_port_stats</code> structure. If an interface does not support a
+ given statistic, then that pair is omitted.
+ </p>
+ <group title="Statistics: Successful transmit and receive counters">
+ <column name="statistics" key="rx_packets">
+ Number of received packets.
+ </column>
+ <column name="statistics" key="rx_bytes">
+ Number of received bytes.
+ </column>
+ <column name="statistics" key="tx_packets">
+ Number of transmitted packets.
+ </column>
+ <column name="statistics" key="tx_bytes">
+ Number of transmitted bytes.
+ </column>
+ </group>
+ <group title="Statistics: Receive errors">
+ <column name="statistics" key="rx_dropped">
+ Number of packets dropped by RX.
+ </column>
+ <column name="statistics" key="rx_frame_err">
+ Number of frame alignment errors.
+ </column>
+ <column name="statistics" key="rx_over_err">
+ Number of packets with RX overrun.
+ </column>
+ <column name="statistics" key="rx_crc_err">
+ Number of CRC errors.
+ </column>
+ <column name="statistics" key="rx_errors">
+ Total number of receive errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ <group title="Statistics: Transmit errors">
+ <column name="statistics" key="tx_dropped">
+ Number of packets dropped by TX.
+ </column>
+ <column name="statistics" key="collisions">
+ Number of collisions.
+ </column>
+ <column name="statistics" key="tx_errors">
+ Total number of transmit errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ </group>
+
+ <group title="Ingress Policing">
+ <p>
+ 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.
+ </p>
+ <p>
+ 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 <ref table="QoS"/> and <ref
+ table="Queue"/> tables).
+ </p>
+ <p>
+ Policing is currently implemented only on Linux. The Linux
+ implementation uses a simple ``token bucket'' approach:
+ </p>
+ <ul>
+ <li>
+ The size of the bucket corresponds to <ref
+ column="ingress_policing_burst"/>. Initially the bucket is full.
+ </li>
+ <li>
+ Whenever a packet is received, its size (converted to tokens) is
+ compared to the number of tokens currently in the bucket. If the
+ required number of tokens are available, they are removed and the
+ packet is forwarded. Otherwise, the packet is dropped.
+ </li>
+ <li>
+ Whenever it is not full, the bucket is refilled with tokens at the
+ rate specified by <ref column="ingress_policing_rate"/>.
+ </li>
+ </ul>
+ <p>
+ 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.
+ </p>
+ <column name="ingress_policing_rate">
+ <p>
+ Maximum rate for data received on this interface, in kbps. Data
+ received faster than this rate is dropped. Set to <code>0</code>
+ (the default) to disable policing.
+ </p>
+ </column>
+
+ <column name="ingress_policing_burst">
+ <p>Maximum burst size for data received on this interface, in kb. The
+ default burst size if set to <code>0</code> is 1000 kb. This value
+ has no effect if <ref column="ingress_policing_rate"/>
+ is <code>0</code>.</p>
+ <p>
+ Specifying a larger burst size lets the algorithm be more forgiving,
+ which is important for protocols like TCP that react severely to
+ dropped packets. The burst size should be at least the size of the
+ interface's MTU. Specifying a value that is numerically at least as
+ large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
+ closer to achieving the full rate.
+ </p>
+ </column>
+ </group>
+
+ <group title="Connectivity Fault Management">
+ <p>
+ 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.
+ </p>
+
+ <p>
+ 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.
+ </p>
+
+ <column name="cfm_mpid">
+ A Maintenance Point ID (MPID) uniquely identifies each endpoint within
+ a Maintenance Association. The MPID is used to identify this endpoint
+ to other Maintenance Points in the MA. Each end of a link being
+ monitored should have a different MPID. Must be configured to enable
+ CFM on this <ref table="Interface"/>.
+ </column>
+
+ <column name="cfm_fault">
+ <p>
+ Indicates a connectivity fault triggered by an inability to receive
+ heartbeats from any remote endpoint. When a fault is triggered on
+ <ref table="Interface"/>s participating in bonds, they will be
+ disabled.
+ </p>
+ <p>
+ Faults can be triggered for several reasons. Most importantly they
+ are triggered when no CCMs are received for a period of 3.5 times the
+ transmission interval. Faults are also triggered when any CCMs
+ indicate that a Remote Maintenance Point is not receiving CCMs but
+ able to send them. Finally, a fault is triggered if a CCM is
+ received which indicates unexpected configuration. Notably, this
+ case arises when a CCM is received which advertises the local MPID.
+ </p>
+ </column>
+
+ <column name="cfm_remote_mpids">
+ When CFM is properly configured, Open vSwitch will occasionally
+ receive CCM broadcasts. These broadcasts contain the MPID of the
+ sending Maintenance Point. The list of MPIDs from which this
+ <ref table="Interface"/> is receiving broadcasts from is regularly
+ collected and written to this column.
+ </column>
+
+ <column name="other_config" key="cfm_interval"
+ type='{"type": "integer"}'>
+ The interval, in milliseconds, between transmissions of CFM heartbeats.
+ Three missed heartbeat receptions indicate a connectivity fault.
+ Defaults to 1000.
+ </column>
+
+ <column name="other_config" key="cfm_extended"
+ type='{"type": "boolean"}'>
+ When <code>true</code>, the CFM module operates in extended mode. This
+ causes it to use a nonstandard destination address to avoid conflicting
+ with compliant implementations which may be running concurrently on the
+ network. Furthermore, extended mode increases the accuracy of the
+ <code>cfm_interval</code> configuration parameter by breaking wire
+ compatibility with 802.1ag compliant implementations. Defaults to
+ <code>false</code>.
+ </column>
+ <column name="other_config" key="cfm_opstate"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ When <code>down</code>, the CFM module marks all CCMs it generates as
+ operationally down without triggering a fault. This allows remote
+ maintenance points to choose not to forward traffic to the
+ <ref table="Interface"/> on which this CFM module is running.
+ Currently, in Open vSwitch, the opdown bit of CCMs affects
+ <ref table="Interface"/>s participating in bonds, and the bundle
+ OpenFlow action. This setting is ignored when CFM is not in extended
+ mode. Defaults to <code>up</code>.
+ </column>
+
+ <column name="other_config" key="cfm_ccm_vlan"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
+ When set, the CFM module will apply a VLAN tag to all CCMs it generates
+ with the given value.
+ </column>
+
+ <column name="other_config" key="cfm_ccm_pcp"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 7}'>
+ When set, the CFM module will apply a VLAN tag to all CCMs it generates
+ with the given PCP value. The VLAN ID of the tag is governed by the
+ value of <ref column="other_config" key="cfm_ccm_vlan"/>. If
+ <ref column="other_config" key="cfm_ccm_vlan"/> is unset, a VLAN ID of
+ zero is used.
+ </column>
+
+ </group>
+
+ <group title="Bonding Configuration">
+ <column name="other_config" key="bond-stable-id"
+ type='{"type": "integer", "minInteger": 1}'>
+ Used in <code>stable</code> bond mode to make slave
+ selection decisions. Allocating <ref column="other_config"
+ key="bond-stable-id"/> values consistently across interfaces
+ participating in a bond will guarantee consistent slave selection
+ decisions across <code>ovs-vswitchd</code> instances when using
+ <code>stable</code> bonding mode.
+ </column>
+
+ <column name="other_config" key="lacp-port-id"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port ID of this <ref table="Interface"/>. Port IDs are
+ used in LACP negotiations to identify individual ports
+ participating in a bond.
+ </column>
+
+ <column name="other_config" key="lacp-port-priority"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port priority of this <ref table="Interface"/>. In LACP
+ negotiations <ref table="Interface"/>s with numerically lower
+ priorities are preferred for aggregation.
+ </column>
+
+ <column name="other_config" key="lacp-aggregation-key"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP aggregation key of this <ref table="Interface"/>. <ref
+ table="Interface"/>s with different aggregation keys may not be active
+ within a given <ref table="Port"/> at the same time.
+ </column>
+ </group>
+
+ <group title="Virtual Machine Identifiers">
+ <p>
+ 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 <code>-uuid</code> 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.
+ </p>
+
+ <column name="external_ids" key="attached-mac">
+ The MAC address programmed into the ``virtual hardware'' for this
+ interface, in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ For Citrix XenServer, this is the value of the <code>MAC</code> field
+ in the VIF record for this interface.
+ </column>
+
+ <column name="external_ids" key="iface-id">
+ A system-unique identifier for the interface. On XenServer, this will
+ commonly be the same as <ref column="external_ids" key="xs-vif-uuid"/>.
+ </column>
+
+ <column name="external_ids" key="xs-vif-uuid">
+ The virtual interface associated with this interface.
+ </column>
+
+ <column name="external_ids" key="xs-network-uuid">
+ The virtual network to which this interface is attached.
+ </column>
+
+ <column name="external_ids" key="xs-vm-uuid">
+ The VM to which this interface belongs.
+ </column>
+ </group>
+
+ <group title="VLAN Splinters">
+ <p>
+ The ``VLAN splinters'' feature increases Open vSwitch compatibility
+ with buggy network drivers in old versions of Linux that do not
+ properly support VLANs when VLAN devices are not used, at some cost
+ in memory and performance.
+ </p>
+
+ <p>
+ When VLAN splinters are enabled on a particular interface, Open vSwitch
+ creates a VLAN device for each in-use VLAN. For sending traffic tagged
+ with a VLAN on the interface, it substitutes the VLAN device. Traffic
+ received on the VLAN device is treated as if it had been received on
+ the interface on the particular VLAN.
+ </p>
+
+ <p>
+ VLAN splinters consider a VLAN to be in use if:
+ </p>
+
+ <ul>
+ <li>
+ The VLAN is the <ref table="Port" column="tag"/> value in any <ref
+ table="Port"/> record.
+ </li>
+
+ <li>
+ The VLAN is listed within the <ref table="Port" column="trunks"/>
+ column of the <ref table="Port"/> record of an interface on which
+ VLAN splinters are enabled.
+
+ An empty <ref table="Port" column="trunks"/> does not influence the
+ in-use VLANs: creating 4,096 VLAN devices is impractical because it
+ will exceed the current 1,024 port per datapath limit.
+ </li>
+
+ <li>
+ An OpenFlow flow within any bridge matches the VLAN.
+ </li>
+ </ul>
+
+ <p>
+ The same set of in-use VLANs applies to every interface on which VLAN
+ splinters are enabled. That is, the set is not chosen separately for
+ each interface but selected once as the union of all in-use VLANs based
+ on the rules above.
+ </p>
+
+ <p>
+ It does not make sense to enable VLAN splinters on an interface for an
+ access port, or on an interface that is not a physical port.
+ </p>
+
+ <p>
+ VLAN splinters are deprecated. When broken device drivers are no
+ longer in widespread use, we will delete this feature.
+ </p>
+
+ <column name="other_config" key="enable-vlan-splinters"
+ type='{"type": "boolean"}'>
+ <p>
+ Set to <code>true</code> to enable VLAN splinters on this interface.
+ Defaults to <code>false</code>.
+ </p>
+
+ <p>
+ VLAN splinters increase kernel and userspace memory overhead, so do
+ not use them unless they are needed.
+ </p>
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Flow_Table" title="OpenFlow table configuration">
+ <p>Configuration for a particular OpenFlow table.</p>
+
+ <column name="name">
+ The table's name. Set this column to change the name that controllers
+ will receive when they request table statistics, e.g. <code>ovs-ofctl
+ dump-tables</code>. The name does not affect switch behavior.
+ </column>
+
+ <column name="flow_limit">
+ If set, limits the number of flows that may be added to the table. Open
+ vSwitch may limit the number of flows in a table for other reasons,
+ e.g. due to hardware limitations or for resource availability or
+ performance reasons.
+ </column>
+
+ <column name="overflow_policy">
+ <p>
+ Controls the switch's behavior when an OpenFlow flow table modification
+ request would add flows in excess of <ref column="flow_limit"/>. The
+ supported values are:
+ </p>
+
+ <dl>
+ <dt><code>refuse</code></dt>
+ <dd>
+ Refuse to add the flow or flows. This is also the default policy
+ when <ref column="overflow_policy"/> is unset.
+ </dd>
+
+ <dt><code>evict</code></dt>
+ <dd>
+ Delete the flow that will expire soonest. See <ref column="groups"/>
+ for details.
+ </dd>
+ </dl>
+ </column>
+
+ <column name="groups">
+ <p>
+ When <ref column="overflow_policy"/> is <code>evict</code>, this
+ controls how flows are chosen for eviction when the flow table would
+ otherwise exceed <ref column="flow_limit"/> flows. Its value is a set
+ of NXM fields or sub-fields, each of which takes one of the forms
+ <code><var>field</var>[]</code> or
+ <code><var>field</var>[<var>start</var>..<var>end</var>]</code>,
+ e.g. <code>NXM_OF_IN_PORT[]</code>. Please see
+ <code>nicira-ext.h</code> for a complete list of NXM field names.
+ </p>
+
+ <p>
+ When a flow must be evicted due to overflow, the flow to evict is
+ chosen through an approximation of the following algorithm:
+ </p>
+
+ <ol>
+ <li>
+ Divide the flows in the table into groups based on the values of the
+ specified fields or subfields, so that all of the flows in a given
+ group have the same values for those fields. If a flow does not
+ specify a given field, that field's value is treated as 0.
+ </li>
+
+ <li>
+ Consider the flows in the largest group, that is, the group that
+ contains the greatest number of flows. If two or more groups all
+ have the same largest number of flows, consider the flows in all of
+ those groups.
+ </li>
+
+ <li>
+ Among the flows under consideration, choose the flow that expires
+ soonest for eviction.
+ </li>
+ </ol>
+
+ <p>
+ 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 <ref column="flow_limit"/>.
+ </p>
+
+ <p>
+ Open vSwitch ignores any invalid or unknown field specifications.
+ </p>
+
+ <p>
+ When <ref column="overflow_policy"/> is not <code>evict</code>, this
+ column has no effect.
+ </p>
+ </column>
+ </table>
+
+ <table name="QoS" title="Quality of Service configuration">
+ <p>Quality of Service (QoS) configuration for each Port that
+ references it.</p>
+
+ <column name="type">
+ <p>The type of QoS to implement. The <ref table="Open_vSwitch"
+ column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
+ identifies the types that a switch actually supports. The currently
+ defined types are listed below:</p>
+ <dl>
+ <dt><code>linux-htb</code></dt>
+ <dd>
+ Linux ``hierarchy token bucket'' classifier. See tc-htb(8) (also at
+ <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
+ (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
+ for information on how this classifier works and how to configure it.
+ </dd>
+ </dl>
+ <dl>
+ <dt><code>linux-hfsc</code></dt>
+ <dd>
+ Linux "Hierarchical Fair Service Curve" classifier.
+ See <code>http://linux-ip.net/articles/hfsc.en/</code> for
+ information on how this classifier works.
+ </dd>
+ </dl>
+ </column>
+
+ <column name="queues">
+ <p>A map from queue numbers to <ref table="Queue"/> records. The
+ supported range of queue numbers depend on <ref column="type"/>. The
+ queue numbers are the same as the <code>queue_id</code> used in
+ OpenFlow in <code>struct ofp_action_enqueue</code> and other
+ structures. Queue 0 is used by OpenFlow output actions that do not
+ specify a specific queue.</p>
+ </column>