+ <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. ToS is interpreted as DSCP and ECN bits, ECN part must be
+ zero. 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
+ disabled; set to <code>true</code> to enable. This feature is
+ deprecated and will be removed soon.
+ </column>
+
+ <group title="Tunnel Options: gre only">
+ <p>
+ Only <code>gre</code> interfaces support these options.
+ </p>
+ </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>
+
+ <p>
+ When operating over tunnels which have no <code>in_key</code>, or an
+ <code>in_key</code> of <code>flow</code>. CFM will only accept CCMs
+ with a tunnel key of zero.
+ </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_fault_status" key="recv">
+ Indicates a CFM fault was triggered due to a lack of CCMs received on
+ the <ref table="Interface"/>.
+ </column>
+
+ <column name="cfm_fault_status" key="rdi">
+ Indicates a CFM fault was triggered due to the reception of a CCM with
+ the RDI bit flagged. Endpoints set the RDI bit in their CCMs when they
+ are not receiving CCMs themselves. This typically indicates a
+ unidirectional connectivity failure.
+ </column>
+
+ <column name="cfm_fault_status" key="maid">
+ Indicates a CFM fault was triggered due to the reception of a CCM with
+ a MAID other than the one Open vSwitch uses. CFM broadcasts are tagged
+ with an identification number in addition to the MPID called the MAID.
+ Open vSwitch only supports receiving CCM broadcasts tagged with the
+ MAID it uses internally.
+ </column>
+
+ <column name="cfm_fault_status" key="loopback">
+ Indicates a CFM fault was triggered due to the reception of a CCM
+ advertising the same MPID configured in the <ref column="cfm_mpid"/>
+ column of this <ref table="Interface"/>. This may indicate a loop in
+ the network.
+ </column>
+
+ <column name="cfm_fault_status" key="overflow">
+ Indicates a CFM fault was triggered because the CFM module received
+ CCMs from more remote endpoints than it can keep track of.
+ </column>
+
+ <column name="cfm_fault_status" key="override">
+ Indicates a CFM fault was manually triggered by an administrator using
+ an <code>ovs-appctl</code> command.
+ </column>
+
+ <column name="cfm_fault_status" key="interval">
+ Indicates a CFM fault was triggered due to the reception of a CCM
+ frame having an invalid interval.
+ </column>
+
+ <column name="cfm_remote_opstate">
+ <p>When in extended mode, indicates the operational state of the
+ remote endpoint as either <code>up</code> or <code>down</code>. See
+ <ref column="other_config" key="cfm_opstate"/>.
+ </p>
+ </column>
+
+ <column name="cfm_health">
+ <p>
+ Indicates the health of the interface as a percentage of CCM frames
+ received over 21 <ref column="other_config" key="cfm_interval"/>s.
+ The health of an interface is undefined if it is communicating with
+ more than one <ref column="cfm_remote_mpids"/>. It reduces if
+ healthy heartbeats are not received at the expected rate, and
+ gradually improves as healthy heartbeats are received at the desired
+ rate. Every 21 <ref column="other_config" key="cfm_interval"/>s, the
+ health of the interface is refreshed.
+ </p>
+ <p>
+ As mentioned above, the faults can be triggered for several reasons.
+ The link health will deteriorate even if heartbeats are received but
+ they are reported to be unhealthy. An unhealthy heartbeat in this
+ context is a heartbeat for which either some fault is set or is out
+ of sequence. The interface health can be 100 only on receiving
+ healthy heartbeats at the desired rate.
+ </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"}'>
+ <p>
+ The interval, in milliseconds, between transmissions of CFM
+ heartbeats. Three missed heartbeat receptions indicate a
+ connectivity fault.
+ </p>
+
+ <p>
+ In standard operation only intervals of 3, 10, 100, 1,000, 10,000,
+ 60,000, or 600,000 ms are supported. Other values will be rounded
+ down to the nearest value on the list. Extended mode (see <ref
+ column="other_config" key="cfm_extended"/>) supports any interval up
+ to 65,535 ms. In either mode, the default is 1000 ms.
+ </p>
+
+ <p>We do not recommend using intervals less than 100 ms.</p>
+ </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. May be the string <code>random</code> in which
+ case each CCM will be tagged with a different randomly generated VLAN.
+ </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="iface-status"
+ type='{"type": "string",
+ "enum": ["set", ["active", "inactive"]]}'>
+ <p>
+ Hypervisors may sometimes have more than one interface associated
+ with a given <ref column="external_ids" key="iface-id"/>, only one of
+ which is actually in use at a given time. For example, in some
+ circumstances XenServer has both a ``tap'' and a ``vif'' interface
+ for a single <ref column="external_ids" key="iface-id"/>, but only
+ uses one of them at a time. A hypervisor that behaves this way must
+ mark the currently in use interface <code>active</code> and the
+ others <code>inactive</code>. A hypervisor that never has more than
+ one interface for a given <ref column="external_ids" key="iface-id"/>
+ may mark that interface <code>active</code> or omit <ref
+ column="external_ids" key="iface-status"/> entirely.
+ </p>
+
+ <p>
+ During VM migration, a given <ref column="external_ids"
+ key="iface-id"/> might transiently be marked <code>active</code> on
+ two different hypervisors. That is, <code>active</code> means that
+ this <ref column="external_ids" key="iface-id"/> is the active
+ instance within a single hypervisor, not in a broader scope.
+ </p>
+ </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="vm-id">
+ The VM to which this interface belongs. On XenServer, this will be the
+ same as <ref column="external_ids" key="xs-vm-uuid"/>.
+ </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>
+
+ <p>
+ VLAN splinters do not support 802.1p priority tags. Received
+ priorities will appear to be 0, regardless of their actual values,
+ and priorities on transmitted packets will also be cleared to 0.
+ </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 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.</p>
+
+ <p>
+ Queue 0 is the ``default queue.'' It is used by OpenFlow output
+ actions when no specific queue has been set. When no configuration for
+ queue 0 is present, it is automatically configured as if a <ref
+ table="Queue"/> record with empty <ref table="Queue" column="dscp"/>
+ and <ref table="Queue" column="other_config"/> columns had been
+ specified.
+ (Before version 1.6, Open vSwitch would leave queue 0 unconfigured in
+ this case. With some queuing disciplines, this dropped all packets
+ destined for the default queue.)
+ </p>
+ </column>
+
+ <group title="Configuration for linux-htb and linux-hfsc">
+ <p>
+ The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
+ the following key-value pair:
+ </p>
+
+ <column name="other_config" key="max-rate" type='{"type": "integer"}'>
+ Maximum rate shared by all queued traffic, in bit/s. Optional. If not
+ specified, for physical interfaces, the default is the link rate. For
+ other interfaces or if the link rate cannot be determined, the default
+ is currently 100 Mbps.
+ </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="Queue" title="QoS output queue.">
+ <p>A configuration for a port output queue, used in configuring Quality of
+ Service (QoS) features. May be referenced by <ref column="queues"
+ table="QoS"/> column in <ref table="QoS"/> table.</p>
+
+ <column name="dscp">
+ If set, Open vSwitch will mark all traffic egressing this
+ <ref table="Queue"/> with the given DSCP bits. Traffic egressing the
+ default <ref table="Queue"/> is only marked if it was explicitly selected
+ as the <ref table="Queue"/> at the time the packet was output. If unset,
+ the DSCP bits of traffic egressing this <ref table="Queue"/> will remain
+ unchanged.
+ </column>
+
+ <group title="Configuration for linux-htb QoS">
+ <p>
+ <ref table="QoS"/> <ref table="QoS" column="type"/>
+ <code>linux-htb</code> may use <code>queue_id</code>s less than 61440.
+ It has the following key-value pairs defined.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even
+ if excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </column>
+
+ <column name="other_config" key="burst"
+ type='{"type": "integer", "minInteger": 1}'>
+ Burst size, in bits. This is the maximum amount of ``credits'' that a
+ queue can accumulate while it is idle. Optional. Details of the
+ <code>linux-htb</code> implementation require a minimum burst size, so
+ a too-small <code>burst</code> will be silently ignored.
+ </column>
+
+ <column name="other_config" key="priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
+ A queue with a smaller <code>priority</code> will receive all the
+ excess bandwidth that it can use before a queue with a larger value
+ receives any. Specific priority values are unimportant; only relative
+ ordering matters. Defaults to 0 if unspecified.
+ </column>
+ </group>
+
+ <group title="Configuration for linux-hfsc QoS">
+ <p>
+ <ref table="QoS"/> <ref table="QoS" column="type"/>
+ <code>linux-hfsc</code> may use <code>queue_id</code>s less than 61440.
+ It has the following key-value pairs defined.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even if
+ excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </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="Mirror" title="Port mirroring.">
+ <p>A port mirror within a <ref table="Bridge"/>.</p>
+ <p>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.</p>
+
+ <column name="name">
+ Arbitrary identifier for the <ref table="Mirror"/>.
+ </column>
+
+ <group title="Selecting Packets for Mirroring">
+ <p>
+ 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.
+ </p>
+
+ <column name="select_all">
+ If true, every packet arriving or departing on any port is
+ selected for mirroring.
+ </column>
+
+ <column name="select_dst_port">
+ Ports on which departing packets are selected for mirroring.
+ </column>
+
+ <column name="select_src_port">
+ Ports on which arriving packets are selected for mirroring.
+ </column>
+
+ <column name="select_vlan">