+ 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>
+
+ </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.