+
+ <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="status">
+ <p>
+ Key-value pairs that report port status. Supported status
+ values are <code>type</code>-dependent; some interfaces may not have
+ a valid <code>driver_name</code>, for example.
+ </p>
+ <p>The currently defined key-value pairs are:</p>
+ <dl>
+ <dt><code>driver_name</code></dt>
+ <dd>The name of the device driver controlling the network
+ adapter.</dd>
+ </dl>
+ <dl>
+ <dt><code>driver_version</code></dt>
+ <dd>The version string of the device driver controlling the
+ network adapter.</dd>
+ </dl>
+ <dl>
+ <dt><code>firmware_version</code></dt>
+ <dd>The version string of the network adapter's firmware, if
+ available.</dd>
+ </dl>
+ <dl>
+ <dt><code>source_ip</code></dt>
+ <dd>The source IP address used for an IPv4 tunnel end-point,
+ such as <code>gre</code> or <code>capwap</code>.</dd>
+ </dl>
+ <dl>
+ <dt><code>tunnel_egress_iface</code></dt>
+ <dd>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 <code>remote_ip</code>.
+ This could be an internal interface such as a bridge port.</dd>
+ </dl>
+ <dl>
+ <dt><code>tunnel_egress_iface_carrier</code></dt>
+ <dd>Whether a carrier is detected on <ref
+ column="tunnel_egress_iface"/>. Valid values are <code>down</code>
+ and <code>up</code>.</dd>
+ </dl>
+ </column>
+ </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="Other Features">
+
+ <column name="monitor">
+ Connectivity monitor configuration for this interface.
+ </column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate
+ with Open vSwitch, rather than by Open vSwitch itself. System
+ integrators should either use the Open vSwitch development
+ mailing list to coordinate on common key-value definitions, or
+ choose key names that are likely to be unique. The currently
+ defined common key-value pairs are:
+ <dl>
+ <dt><code>attached-mac</code></dt>
+ <dd>
+ 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.</dd>
+ <dt><code>iface-id</code></dt>
+ <dd>A system-unique identifier for the interface. On XenServer,
+ this will commonly be the same as <code>xs-vif-uuid</code>.</dd>
+ </dl>
+ <p>
+ Additionally the following 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>
+ <p>The currently defined key-value pairs for XenServer are:</p>
+ <dl>
+ <dt><code>xs-vif-uuid</code></dt>
+ <dd>The virtual interface associated with this interface.</dd>
+ <dt><code>xs-network-uuid</code></dt>
+ <dd>The virtual network to which this interface is attached.</dd>
+ <dt><code>xs-vm-uuid</code></dt>
+ <dd>The VM to which this interface belongs.</dd>
+ </dl>
+ </column>
+
+ <column name="other_config">
+ Key-value pairs for rarely used interface features.
+ <dl>
+ <dt><code>lacp-port-priority</code></dt>
+ <dd> The LACP port priority of this <ref table="Interface"/>. In
+ LACP negotiations <ref table="Interface"/>s with numerically lower
+ priorities are preferred for aggregation. Must be a number between
+ 1 and 65535.</dd>
+ </dl>
+ </column>
+
+ <column name="statistics">
+ <p>
+ Key-value pairs that report interface statistics. The current
+ implementation updates these counters periodically. In the future,
+ we plan to, instead, 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>
+ The currently defined key-value pairs are listed below. 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>
+ <ul>
+ <li>
+ Successful transmit and receive counters:
+ <dl>
+ <dt><code>rx_packets</code></dt>
+ <dd>Number of received packets.</dd>
+ <dt><code>rx_bytes</code></dt>
+ <dd>Number of received bytes.</dd>
+ <dt><code>tx_packets</code></dt>
+ <dd>Number of transmitted packets.</dd>
+ <dt><code>tx_bytes</code></dt>
+ <dd>Number of transmitted bytes.</dd>
+ </dl>
+ </li>
+ <li>
+ Receive errors:
+ <dl>
+ <dt><code>rx_dropped</code></dt>
+ <dd>Number of packets dropped by RX.</dd>
+ <dt><code>rx_frame_err</code></dt>
+ <dd>Number of frame alignment errors.</dd>
+ <dt><code>rx_over_err</code></dt>
+ <dd>Number of packets with RX overrun.</dd>
+ <dt><code>rx_crc_err</code></dt>
+ <dd>Number of CRC errors.</dd>
+ <dt><code>rx_errors</code></dt>
+ <dd>
+ Total number of receive errors, greater than or equal
+ to the sum of the above.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Transmit errors:
+ <dl>
+ <dt><code>tx_dropped</code></dt>
+ <dd>Number of packets dropped by TX.</dd>
+ <dt><code>collisions</code></dt>
+ <dd>Number of collisions.</dd>
+ <dt><code>tx_errors</code></dt>
+ <dd>
+ Total number of transmit errors, greater
+ than or equal to the sum of the above.
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </column>
+ </group>
+ </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>
+
+ <column name="other_config">
+ <p>Key-value pairs for configuring QoS features that depend on
+ <ref column="type"/>.</p>
+ <p>The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
+ the following key-value pairs:</p>
+ <dl>
+ <dt><code>max-rate</code></dt>
+ <dd>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.</dd>
+ </dl>
+ </column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
+ </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="other_config">
+ <p>Key-value pairs for configuring the output queue. The supported
+ key-value pairs and their meanings depend on the <ref column="type"/>
+ of the <ref column="QoS"/> records that reference this row.</p>
+ <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
+ column="type"/> of <code>min-rate</code> are:</p>
+ <dl>
+ <dt><code>min-rate</code></dt>
+ <dd>Minimum guaranteed bandwidth, in bit/s. Required. The
+ floor value is 1500 bytes/s (12,000 bit/s).</dd>
+ </dl>
+ <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
+ column="type"/> of <code>linux-htb</code> are:</p>
+ <dl>
+ <dt><code>min-rate</code></dt>
+ <dd>Minimum guaranteed bandwidth, in bit/s. Required.</dd>
+ <dt><code>max-rate</code></dt>
+ <dd>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.</dd>
+ <dt><code>burst</code></dt>
+ <dd>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.</dd>
+ <dt><code>priority</code></dt>
+ <dd>A nonnegative 32-bit integer. Defaults to 0 if
+ unspecified. 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.</dd>
+ </dl>
+ <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
+ column="type"/> of <code>linux-hfsc</code> are:</p>
+ <dl>
+ <dt><code>min-rate</code></dt>
+ <dd>Minimum guaranteed bandwidth, in bit/s. Required.</dd>
+ <dt><code>max-rate</code></dt>
+ <dd>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.</dd>
+ </dl>
+ </column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
+ </table>
+
+ <table name="Monitor" title="Connectivity Monitor configuration">
+ <p>
+ A <ref table="Monitor"/> attaches to an <ref table="Interface"/> to
+ implement 802.1ag Connectivity Fault Management (CFM). 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. A <ref table="Monitor"/> is
+ responsible for collecting data about other MPs in its MA and
+ broadcasting CCMs.
+ </p>
+
+ <group title="Monitor Configuration">
+ <column name="mpid">
+ A Maintenance Point ID (MPID) uniquely identifies each endpoint within
+ a Maintenance Association (see <ref column="ma_name"/>). The MPID is
+ used to identify this <ref table="Monitor"/> to other endpoints in the
+ MA.
+ </column>
+
+ <column name="remote_mps">
+ A set of <ref table="Maintenance_Points"/> which this
+ <ref table="Monitor"/> should have connectivity to. If this
+ <ref table="Monitor"/> does not have connectivity to any MPs in this
+ set, or has connectivity to any MPs not in this set, a fault is
+ signaled.
+ </column>
+
+ <column name="ma_name">
+ A Maintenance Association (MA) name pairs with a Maintenance Domain
+ (MD) name to uniquely identify a MA. A MA is a group of endpoints who
+ have complete and exclusive interconnectivity. Defaults to
+ <code>ovs</code> if unset.
+ </column>
+
+ <column name="md_name">
+ A Maintenance Domain name pairs with a Maintenance Association name to
+ uniquely identify a MA. Defaults to <code>ovs</code> if unset.
+ </column>
+
+ <column name="interval">
+ The transmission interval of CCMs in milliseconds. Three missed CCMs
+ indicate a connectivity fault. Defaults to 1000ms.
+ </column>
+ </group>
+
+ <group title="Monitor Status">
+ <column name="unexpected_remote_mpids">
+ A set of MPIDs representing MPs to which this <ref table="Monitor"/>
+ has detected connectivity that are not in the
+ <ref column="remote_mps"/> set. This <ref table="Monitor"/> should not
+ have connectivity to any MPs not listed in <ref column="remote_mps"/>.
+ Thus, if this set is non-empty a fault is indicated.
+ </column>
+
+ <column name="unexpected_remote_maids">
+ A set of MAIDs representing foreign Maintenance Associations (MAs)
+ which this <ref table="Monitor"/> has detected connectivity to. A
+ <ref table="Monitor"/> should not have connectivity to a Maintenance
+ Association other than its own. Thus, if this set is non-empty a fault
+ is indicated.
+ </column>
+
+ <column name="fault">
+ Indicates a Connectivity Fault caused by a configuration error, a down
+ remote MP, or unexpected connectivity to a remote MAID or remote MP.
+ </column>
+ </group>
+ </table>
+
+ <table name="Maintenance_Point" title="Maintenance Point configuration">
+ <p>
+ A <ref table="Maintenance_Point"/> represents a MP which a
+ <ref table="Monitor"/> has or should have connectivity to.
+ </p>
+
+ <group title="Maintenance_Point Configuration">
+ <column name="mpid">
+ A Maintenance Point ID (MPID) uniquely identifies each endpoint within
+ a Maintenance Association. All MPs within a MA should have a unique
+ MPID.
+ </column>
+ </group>
+
+ <group title="Maintenance_Point Status">
+ <column name="fault">
+ Indicates a connectivity fault.
+ </column>
+ </group>