X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=vswitchd%2Fvswitch.xml;h=7739793cfb13709a1272296c5a39d4dd6669e115;hb=c473936b9af693ad88907e739013f34d9c70860d;hp=55880b80ecc210bfdb3a32f5963600abae5e8920;hpb=9ae7ddc08260134e4dcba618ba9dc6a09298c756;p=sliver-openvswitch.git

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index 55880b80e..7739793cf 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -87,14 +87,6 @@
         configuration changes.
       </column>
 
-      <column name="capabilities">
-        Describes functionality supported by the hardware and software platform
-        on which this Open vSwitch is based.  Clients should not modify this
-        column.  See the <ref table="Capability"/> description for defined
-        capability categories and the meaning of associated
-        <ref table="Capability"/> records.
-      </column>
-
       <group title="Statistics">
         <p>
           The <code>statistics</code> column contains key-value pairs that
@@ -372,8 +364,25 @@
 
     <group title="OpenFlow Configuration">
       <column name="controller">
-        OpenFlow controller set.  If unset, then no OpenFlow controllers
-        will be used.
+        <p>
+          OpenFlow controller set.  If unset, then no OpenFlow controllers
+          will be used.
+        </p>
+
+        <p>
+          If there are primary controllers, removing all of them clears the
+          flow table.  If there are no primary controllers, adding one also
+          clears the flow table.  Other changes to the set of controllers, such
+          as adding or removing a service controller, adding another primary
+          controller to supplement an existing primary controller, or removing
+          only one of two primary controllers, have no effect on the flow
+          table.
+        </p>
+      </column>
+
+      <column name="flow_tables">
+        Configuration for OpenFlow tables.  Each pair maps from an OpenFlow
+        table ID to configuration for that table.
       </column>
 
       <column name="fail_mode">
@@ -406,6 +415,10 @@
         <p>When more than one controller is configured,
         <ref column="fail_mode"/> is considered only when none of the
         configured controllers can be contacted.</p>
+        <p>
+          Changing <ref column="fail_mode"/> when no primary controllers are
+          configured clears the flow table.
+        </p>
       </column>
 
       <column name="datapath_id">
@@ -446,7 +459,7 @@
         on bridges.  Bond, internal, and mirror ports are not supported
         and will not participate in the spanning tree.
       </column>
- 
+
       <column name="other_config" key="stp-system-id">
         The bridge's STP identifier (the lower 48 bits of the bridge-id)
         in the form
@@ -537,6 +550,26 @@
         should be enabled.  Default is disabled, set to
         <code>true</code> to enable.
       </column>
+
+      <column name="other_config" key="mac-aging-time"
+              type='{"type": "integer", "minInteger": 1}'>
+        <p>
+          The maximum number of seconds to retain a MAC learning entry for
+          which no packets have been seen.  The default is currently 300
+          seconds (5 minutes).  The value, if specified, is forced into a
+          reasonable range, currently 15 to 3600 seconds.
+        </p>
+
+        <p>
+          A short MAC aging time allows a network to more quickly detect that a
+          host is no longer connected to a switch port.  However, it also makes
+          it more likely that packets will be flooded unnecessarily, when they
+          are addressed to a connected host that rarely transmits packets.  To
+          reduce the incidence of unnecessary flooding, use a MAC aging time
+          longer than the maximum interval at which a host will ordinarily
+          transmit packets.
+        </p>
+      </column>
     </group>
 
     <group title="Bridge Status">
@@ -741,8 +774,7 @@
 
       <p>
         The following modes require the upstream switch to support 802.3ad with
-        successful LACP negotiation.  If LACP negotiation fails then
-        <code>balance-slb</code> style flow hashing is used as a fallback:
+        successful LACP negotiation:
       </p>
 
       <dl>
@@ -774,10 +806,19 @@
 
       <column name="bond_mode">
         <p>The type of bonding used for a bonded port.  Defaults to
-        <code>balance-slb</code> if unset.
+        <code>active-backup</code> if unset.
         </p>
       </column>
 
+      <column name="other_config" key="bond-hash-basis"
+              type='{"type": "integer"}'>
+        An integer hashed along with flows when choosing output slaves in load
+        balanced bonds.  When changed, all flows will be assigned different
+        hash values possibly causing slave selection decisions to change.  Does
+        not affect bonding modes which do not employ load balancing such as
+        <code>active-backup</code>.
+      </column>
+
       <group title="Link Failure Detection">
         <p>
           An important part of link bonding is detecting that links are down so
@@ -836,14 +877,16 @@
           connected to.  <code>active</code> ports are allowed to initiate LACP
           negotiations.  <code>passive</code> ports are allowed to participate
           in LACP negotiations initiated by a remote switch, but not allowed to
-          initiate such negotiations themselves.  Defaults to <code>off</code>
-          if unset.
+          initiate such negotiations themselves.  If LACP is enabled on a port
+          whose partner switch does not support LACP, the bond will be
+          disabled.  Defaults to <code>off</code> if unset.
         </column>
 
         <column name="other_config" key="lacp-system-id">
           The LACP system ID of this <ref table="Port"/>.  The system ID of a
           LACP bond is used to identify itself to its partners.  Must be a
-          nonzero MAC address.
+          nonzero MAC address. Defaults to the bridge Ethernet address if
+          unset.
         </column>
 
         <column name="other_config" key="lacp-system-priority"
@@ -881,13 +924,6 @@
           when this mode is in use.  The default if not specified is
           <code>false</code>.
         </column>
-
-        <column name="other_config" key="bond-hash-basis"
-                type='{"type": "integer"}'>
-          An integer hashed along with flows when choosing output slaves.  When
-          changed, all flows will be assigned different hash values possibly
-          causing slave selection decisions to change.
-        </column>
       </group>
 
       <group title="SLB Configuration">
@@ -899,11 +935,13 @@
         </p>
 
         <column name="other_config" key="bond-rebalance-interval"
-                type='{"type": "integer", "minInteger": 1000, "maxInteger": 10000}'>
-          For an SLB bonded port, the number of milliseconds between successive
-          attempts to rebalance the bond, that is, to move source MACs and
-          their flows from one interface on the bond to another in an attempt
-          to keep usage of each interface roughly equal.
+                type='{"type": "integer", "minInteger": 0, "maxInteger": 10000}'>
+          For a load balanced bonded port, the number of milliseconds between
+          successive attempts to rebalance the bond, that is, to move flows
+          from one interface on the bond to another in an attempt to keep usage
+          of each interface roughly equal.  If zero, load balancing is disabled
+          on the bond (carrier status changes still cause flows to move).  If
+          less than 1000ms, the rebalance interval will be 1000ms.
         </column>
       </group>
 
@@ -1123,7 +1161,7 @@
           <dt><code>ipsec_gre</code></dt>
           <dd>
             An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
-            IPsec tunnel.  
+            IPsec tunnel.
           </dd>
 
           <dt><code>capwap</code></dt>
@@ -1251,7 +1289,7 @@
         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
@@ -1517,7 +1555,7 @@
           Total number of receive errors, greater than or equal to the sum of
           the above.
         </column>
-      </group>              
+      </group>
       <group title="Statistics: Transmit errors">
         <column name="statistics" key="tx_dropped">
           Number of packets dropped by TX.
@@ -1653,6 +1691,43 @@
         </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_remote_mpids">
         When CFM is properly configured, Open vSwitch will occasionally
         receive CCM broadcasts.  These broadcasts contain the MPID of the
@@ -1696,6 +1771,15 @@
         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">
@@ -1763,6 +1847,11 @@
         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>
@@ -1789,6 +1878,11 @@
       </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
@@ -1832,6 +1926,12 @@
           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>
 
@@ -1844,15 +1944,106 @@
     </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>
+      <p>The type of QoS to implement. The currently defined types are
+      listed below:</p>
       <dl>
         <dt><code>linux-htb</code></dt>
         <dd>
@@ -1877,8 +2068,19 @@
       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>
+      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">
@@ -1886,7 +2088,7 @@
         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
@@ -1918,25 +2120,13 @@
       unchanged.
     </column>
 
-    <group title="Configuration for min-rate QoS">
-      <p>
-        These key-value pairs are defined for <ref table="QoS"/> <ref
-        table="QoS" column="type"/> of <code>min-rate</code>.
-      </p>
-      
-      <column name="other_config" key="min-rate"
-              type='{"type": "integer", "minInteger": 12000}'>
-        Minimum guaranteed bandwidth, in bit/s.  Required.  The floor value is
-        1500 bytes/s (12,000 bit/s).
-      </column>
-    </group>
-
     <group title="Configuration for linux-htb QoS">
       <p>
-        These key-value pairs are defined for <ref table="QoS"/> <ref
-        table="QoS" column="type"/> of <code>linux-htb</code>.
+        <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.
@@ -1969,15 +2159,16 @@
 
     <group title="Configuration for linux-hfsc QoS">
       <p>
-        These key-value pairs are defined for <ref table="QoS"/> <ref
-        table="QoS" column="type"/> of <code>linux-hfsc</code>.
+        <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
@@ -2125,6 +2316,18 @@
       </column>
     </group>
 
+    <group title="Statistics: Mirror counters">
+      <p>
+        Key-value pairs that report mirror statistics.
+      </p>
+      <column name="statistics" key="tx_packets">
+        Number of packets transmitted through this mirror.
+      </column>
+      <column name="statistics" key="tx_bytes">
+        Number of bytes transmitted through this mirror.
+      </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.
@@ -2298,25 +2501,50 @@
       </column>
     </group>
 
-    <group title="OpenFlow Rate Limiting">
+    <group title="Asynchronous Message Configuration">
+      <p>
+        OpenFlow switches send certain messages to controllers spontanenously,
+        that is, not in response to any request from the controller.  These
+        messages are called ``asynchronous messages.''  These columns allow
+        asynchronous messages to be limited or disabled to ensure the best use
+        of network resources.
+      </p>
+
+      <column name="enable_async_messages">
+        The OpenFlow protocol enables asynchronous messages at time of
+        connection establishment, which means that a controller can receive
+        asynchronous messages, potentially many of them, even if it turns them
+        off immediately after connecting.  Set this column to
+        <code>false</code> to change Open vSwitch behavior to disable, by
+        default, all asynchronous messages.  The controller can use the
+        <code>NXT_SET_ASYNC_CONFIG</code> Nicira extension to OpenFlow to turn
+        on any messages that it does want to receive, if any.
+      </column>
+
       <column name="controller_rate_limit">
-        <p>The maximum rate at which packets in unknown flows will be
-        forwarded to the OpenFlow controller, in packets per second.  This
-        feature prevents a single bridge from overwhelming the controller.
-        If not specified, the default is implementation-specific.</p>
-        <p>In addition, when a high rate triggers rate-limiting, Open
-        vSwitch queues controller packets for each port and transmits
-        them to the controller at the configured rate.  The number of
-        queued packets is limited by
-        the <ref column="controller_burst_limit"/> value.  The packet
-        queue is shared fairly among the ports on a bridge.</p><p>Open
-        vSwitch maintains two such packet rate-limiters per bridge.
-        One of these applies to packets sent up to the controller
-        because they do not correspond to any flow.  The other applies
-        to packets sent up to the controller by request through flow
-        actions. When both rate-limiters are filled with packets, the
-        actual rate that packets are sent to the controller is up to
-        twice the specified rate.</p>
+        <p>
+          The maximum rate at which the switch will forward packets to the
+          OpenFlow controller, in packets per second.  This feature prevents a
+          single bridge from overwhelming the controller.  If not specified,
+          the default is implementation-specific.
+        </p>
+
+        <p>
+          In addition, when a high rate triggers rate-limiting, Open vSwitch
+          queues controller packets for each port and transmits them to the
+          controller at the configured rate.  The <ref
+          column="controller_burst_limit"/> value limits the number of queued
+          packets.  Ports on a bridge share the packet queue fairly.
+        </p>
+
+        <p>
+          Open vSwitch maintains two such packet rate-limiters per bridge: one
+          for packets sent up to the controller because they do not correspond
+          to any flow, and the other for packets sent up to the controller by
+          request through flow actions. When both rate-limiters are filled with
+          packets, the actual rate that packets are sent to the controller is
+          up to twice the specified rate.
+        </p>
       </column>
 
       <column name="controller_burst_limit">
@@ -2416,14 +2644,14 @@
           human consumption.
         </p>
       </column>
-      
+
       <column name="status" key="sec_since_connect"
               type='{"type": "integer", "minInteger": 0}'>
         The amount of time since this controller last successfully connected to
         the switch (in seconds).  Value is empty if controller has never
         successfully connected.
       </column>
-      
+
       <column name="status" key="sec_since_disconnect"
               type='{"type": "integer", "minInteger": 1}'>
         The amount of time since this controller last disconnected from
@@ -2757,10 +2985,12 @@
 
     <column name="agent">
       Name of the network device whose IP address should be reported as the
-      ``agent address'' to collectors.  If not specified, the IP address
+      ``agent address'' to collectors.  If not specified, the agent device is
+      figured from the first target address and the routing table.  If the
+      routing table does not contain a route to the target, the IP address
       defaults to the <ref table="Controller" column="local_ip"/> in the
       collector's <ref table="Controller"/>.  If an agent IP address cannot be
-      determined either way, sFlow is disabled.
+      determined any of these ways, sFlow is disabled.
     </column>
 
     <column name="header">
@@ -2792,46 +3022,4 @@
     </group>
   </table>
 
-  <table name="Capability">
-    <p>Records in this table describe functionality supported by the hardware
-    and software platform on which this Open vSwitch is based.  Clients
-    should not modify this table.</p>
-
-    <p>A record in this table is meaningful only if it is referenced by the
-    <ref table="Open_vSwitch" column="capabilities"/> column in the
-    <ref table="Open_vSwitch"/> table.  The key used to reference it, called
-    the record's ``category,'' determines the meanings of the
-    <ref column="details"/> column.  The following general forms of
-    categories are currently defined:</p>
-
-    <dl>
-      <dt><code>qos-<var>type</var></code></dt>
-      <dd><var>type</var> is supported as the value for
-      <ref column="type" table="QoS"/> in the <ref table="QoS"/> table.
-      </dd>
-    </dl>
-
-    <column name="details">
-      <p>Key-value pairs that describe capabilities.  The meaning of the pairs
-      depends on the category key that the <ref table="Open_vSwitch"
-      column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
-      uses to reference this record, as described above.</p>
-
-      <p>The presence of a record for category <code>qos-<var>type</var></code>
-      indicates that the switch supports <var>type</var> as the value of
-      the <ref table="QoS" column="type"/> column in the <ref table="QoS"/>
-      table.  The following key-value pairs are defined to further describe
-      QoS capabilities:</p>
-
-      <dl>
-        <dt><code>n-queues</code></dt>
-        <dd>Number of supported queues, as a positive integer.  Keys in the
-        <ref table="QoS" column="queues"/> column for <ref table="QoS"/>
-        records whose <ref table="QoS" column="type"/> value
-        equals <var>type</var> must range between 0 and this value minus one,
-        inclusive.</dd>
-      </dl>
-    </column>
-  </table>
-
 </database>