+
+ <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. And extended
+ mode allows eight byte MPIDs. Defaults to <code>false</code>.
+ </column>
+
+ <column name="other_config" key="cfm_demand" type='{"type": "boolean"}'>
+ <p>
+ When <code>true</code>, and
+ <ref column="other_config" key="cfm_extended"/> is true, the CFM
+ module operates in demand mode. When in demand mode, traffic
+ received on the <ref table="Interface"/> is used to indicate
+ liveness. CCMs are still transmitted and received. At least one
+ CCM must be received every 100 * <ref column="other_config"
+ key="cfm_interval"/> amount of time. Otherwise, even if traffic
+ are received, the CFM module will raise the connectivity fault.
+ </p>
+
+ <p>
+ Demand mode has a couple of caveats:
+ <ul>
+ <li>
+ To ensure that ovs-vswitchd has enough time to pull statistics
+ from the datapath, the fault detection interval is set to
+ 3.5 * MAX(<ref column="other_config" key="cfm_interval"/>, 500)
+ ms.
+ </li>
+
+ <li>
+ To avoid ambiguity, demand mode disables itself when there are
+ multiple remote maintenance points.
+ </li>
+
+ <li>
+ If the <ref table="Interface"/> is heavily congested, CCMs
+ containing the <ref column="other_config" key="cfm_opstate"/>
+ status may be dropped causing changes in the operational state to
+ be delayed. Similarly, if CCMs containing the RDI bit are not
+ received, unidirectional link failures may not be detected.
+ </li>
+ </ul>
+ </p>
+ </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="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.
+ There is one exception: some hypervisors support ``migration'' from a
+ given hypervisor to itself (most often for test purposes). During
+ such a ``migration,'' two instances of a single <ref
+ column="external_ids" key="iface-id"/> might both be briefly marked
+ <code>active</code> on a single hypervisor.
+ </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>
+
+ <column name="prefixes">
+ <p>
+ This string set specifies which fields should be used for
+ address prefix tracking. Prefix tracking allows the
+ classifier to skip rules with longer than necessary prefixes,
+ resulting in better wildcarding for datapath flows.
+ </p>
+ <p>
+ Prefix tracking may be beneficial when a flow table contains
+ matches on IP address fields with different prefix lengths.
+ For example, when a flow table contains IP address matches on
+ both full addresses and proper prefixes, the full address
+ matches will typically cause the datapath flow to un-wildcard
+ the whole address field (depending on flow entry priorities).
+ In this case each packet with a different address gets handed
+ to the userspace for flow processing and generates its own
+ datapath flow. With prefix tracking enabled for the address
+ field in question packets with addresses matching shorter
+ prefixes would generate datapath flows where the irrelevant
+ address bits are wildcarded, allowing the same datapath flow
+ to handle all the packets within the prefix in question. In
+ this case many userspace upcalls can be avoided and the
+ overall performance can be better.
+ </p>
+ <p>
+ This is a performance optimization only, so packets will
+ receive the same treatment with or without prefix tracking.
+ </p>
+ <p>
+ The supported fields are: <code>tun_id</code>,
+ <code>tun_src</code>, <code>tun_dst</code>,
+ <code>nw_src</code>, <code>nw_dst</code> (or aliases
+ <code>ip_src</code> and <code>ip_dst</code>),
+ <code>ipv6_src</code>, and <code>ipv6_dst</code>. (Using this
+ feature for <code>tun_id</code> would only make sense if the
+ tunnel IDs have prefix structure similar to IP addresses.)
+ </p>
+ <p>
+ For example, <code>prefixes=ip_dst,ip_src</code> instructs the
+ flow classifier to track the IP destination and source
+ addresses used by the rules in this specific flow table. To
+ set the prefix fields, the flow table record needs to exist:
+ </p>
+ <dl>
+ <dt><code>ovs-vsctl set Bridge br0 flow_tables:0=@N1 -- --id=@N1 create Flow_Table name=table0</code></dt>
+ <dd>
+ Creates a flow table record for the OpenFlow table number 0.
+ </dd>
+
+ <dt><code>ovs-vsctl set Flow_Table table0 prefixes=ip_dst,ip_src</code></dt>
+ <dd>
+ Enables prefix tracking for IP source and destination
+ address fields.
+ </dd>
+ </dl>
+
+ <p>
+ There is a maximum number of fields that can be enabled for any
+ one flow table. Currently this limit is 3.
+ </p>
+ </column>
+
+ <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="external_ids"/>