X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=vswitchd%2Fvswitch.xml;h=b93a8db2068686fa0a810cba0b13105b7719d6c8;hb=0b3f2725391c561cb53e4a7a860648a116f04e08;hp=b21b56004f06986571f5ca5c9f52e6648bad3cdf;hpb=8936565369410daa099708be4cd3fa7e0e39bade;p=openvswitch

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index b21b5600..b93a8db2 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -16,10 +16,9 @@
       </column>
 
       <column name="controller">
-        Default <ref table="Controller"/> used by bridges.  If a
-        <ref table="Bridge"/> record has a <ref table="Bridge"
-        column="controller"/> column, then this
-        <ref table="Controller"/> is used instead.
+        Default OpenFlow <ref table="Controller"/> set used by bridges.  May be
+        overridden on a per-bridge basis by the <ref table="Bridge"
+        column="controller"/> column in <ref table="Bridge"/>.
       </column>
 
       <column name="managers">
@@ -30,6 +29,18 @@
       <column name="ssl">
         SSL used globally by the daemon.
       </column>
+
+      <column name="external_ids">
+        Key-value pairs that identify this Open vSwitch's role in
+        external systems.  The currently defined key-value pairs are:
+        <dl>
+          <dt><code>system-uuid</code></dt>
+          <dd>A universally unique identifier for the Open vSwitch's
+            physical host.  The form of the identifier depends on the
+            type of the host.  On a Citrix XenServer, this is the host
+            UUID displayed by, e.g., <code>xe host-list</code>.</dd>
+        </dl>
+      </column>
     </group>
 
     <group title="Status">
@@ -42,9 +53,37 @@
 
       <column name="cur_cfg">
         Sequence number that Open vSwitch sets to the current value of
-        <ref column="next_cfg"/> after it finishing applying a set of
+        <ref column="next_cfg"/> after it finishes applying a set of
         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>
+
+      <column name="statistics">
+        <p>
+          Key-value pairs that report statistics about a running Open_vSwitch
+          daemon.  The current implementation updates these counters
+          periodically.  In the future, we plan to, instead, update them only
+          when they are queried (e.g. using an OVSDB <code>select</code>
+          operation) and perhaps at other times, but not on any regular
+          periodic basis.</p>
+        <p>
+          The currently defined key-value pairs are listed below.  Some Open
+          vSwitch implementations may not support some statistics, in which
+          case those key-value pairs are omitted.</p>
+        <dl>
+          <dt><code>load-average</code></dt>
+          <dd>
+            System load average multiplied by 100 and rounded to the nearest
+            integer.</dd>
+        </dl>
+      </column>
     </group>
   </table>
 
@@ -93,14 +132,18 @@
 
     <group title="OpenFlow Configuration">
       <column name="controller">
-        OpenFlow controller.  If unset, defaults to that specified by
-        <ref column="controller" table="Open_vSwitch"/> in the
-        <ref table="Open_vSwitch"/> table.  If the default is also unset, then
-        no OpenFlow controller will be used.
+        OpenFlow controller set.  If unset, defaults to the set of
+        controllers specified by <ref column="controller"
+        table="Open_vSwitch"/> in the <ref table="Open_vSwitch"/>
+        table.  If the default is also unset, then no OpenFlow
+        controllers will be used.
       </column>
 
       <column name="datapath_id">
-        Reports the OpenFlow datapath ID in use.  Exactly 12 hex digits.
+        Reports the OpenFlow datapath ID in use.  Exactly 16 hex
+        digits.  (Setting this column will have no useful effect.  Set
+        <ref column="other_config"/>:<code>other-config</code>
+        instead.)
       </column>
     </group>
 
@@ -115,12 +158,12 @@
         Key-value pairs that identify this bridge's role in external systems.
         The currently defined key-value pairs are:
         <dl>
-          <dt><code>xs-network-uuids</code></dt>
-          <dd>Space-delimited set of the Citrix XenServer network UUIDs with
-            which this bridge is associated.</dd>
-          <dt><code>xs-network-names</code></dt>
-          <dd>Semicolon-delimited set of Citrix XenServer network names with
-            which this bridge is associated.</dd>
+          <dt><code>network-uuids</code></dt>
+          <dd>Semicolon-delimited set of universally unique identifier(s) for
+            the network with which this bridge is associated.  The form of the
+            identifier(s) depends on the type of the host.  On a Citrix
+            XenServer host, the network identifiers are RFC 4122 UUIDs as
+            displayed by, e.g., <code>xe network-list</code>.</dd>
         </dl>
       </column>
 
@@ -129,11 +172,11 @@
         features.  The currently defined key-value pairs are:
         <dl>
           <dt><code>datapath-id</code></dt>
-          <dd>Exactly 12 hex
+          <dd>Exactly 16 hex
             digits to set the OpenFlow datapath ID to a specific
             value.</dd>
           <dt><code>hwaddr</code></dt>
-          <dd>Exactly 12 hex digits in the form
+          <dd>An Ethernet address in the form
             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
             to set the hardware address of the local port and influence the
             datapath ID.</dd>
@@ -145,7 +188,7 @@
   <table name="Port" table="Port or bond configuration.">
     <p>A port within a <ref table="Bridge"/>.</p>
     <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
-      <ref column="interface"/> column.  Such a port logically
+      <ref column="interfaces"/> column.  Such a port logically
       corresponds to a port on a physical Ethernet switch.  A port
       with more than one interface is a ``bonded port'' (see
       <ref group="Bonding Configuration"/>).</p>
@@ -168,37 +211,48 @@
       <p>A bridge port must be configured for VLANs in one of two
         mutually exclusive ways:
         <ul>
-          <li>A ``trunk port'' has an empty value for
-            <ref column="tag"/> and a possibly non-empty
-            <ref column="trunks"/> value.</li>
+          <li>A ``trunk port'' has an empty value for <ref
+            column="tag"/>.  Its <ref column="trunks"/> value may be
+            empty or non-empty.</li>
           <li>An ``implicitly tagged VLAN port'' or ``access port''
-            has an nonempty value for <ref column="tag"/> and an empty
-            <ref column="trunks"/> value.</li>
+            has an nonempty value for <ref column="tag"/>.  Its
+            <ref column="trunks"/> value must be empty.</li>
         </ul>
         If <ref column="trunks"/> and <ref column="tag"/> are both
         nonempty, the configuration is ill-formed.
       </p>
 
       <column name="tag">
-        <p>If nonempty, this port's implicitly tagged VLAN.  Frames
-          arriving on trunk ports will be forwarded to this port only
-          if they are tagged with the given VLAN.  Frames arriving on
-          other VLAN ports will be forwarded to this port only if they
-          have the same <ref column="tag"/> value.  Frames forwarded
-          to this port will not have an 802.1Q header.</p>
-        <p>When a frame with a 802.1Q header that indicates a nonzero VLAN is
-          received on an implicit VLAN port, it is discarded.</p>
-        <p>Must be empty if this is a trunk port.</p>
+        <p>
+          If this is an access port (see above), the port's implicitly
+          tagged VLAN.  Must be empty if this is a trunk port.
+        </p>
+        <p>
+          Frames arriving on trunk ports will be forwarded to this
+          port only if they are tagged with the given VLAN (or, if
+          <ref column="tag"/> is 0, then if they lack a VLAN header).
+          Frames arriving on other access ports will be forwarded to
+          this port only if they have the same <ref column="tag"/>
+          value.  Frames forwarded to this port will not have an
+          802.1Q header.
+        </p>
+        <p>
+          When a frame with a 802.1Q header that indicates a nonzero
+          VLAN is received on an access port, it is discarded.
+        </p>
       </column>
 
       <column name="trunks">
-        <p>The 802.1Q VLAN(s) that this port trunks.  If the column is
-          empty, then the port trunks all VLANs as well as packets that
-          have no VLAN header.  Otherwise, only frames that have an
-          802.1Q header with one of the specified VLANs are accepted.
-          If <code>0</code> is included, then frames without an 802.1Q
-          header are also accepted.</p>
-        <p>Must be empty unless this is a trunk port.</p>
+        <p>
+          If this is a trunk port (see above), the 802.1Q VLAN(s) that
+          this port trunks; if it is empty, then the port trunks all
+          VLANs.  Must be empty if this is an access port.
+        </p>
+        <p>
+          Frames arriving on trunk ports are dropped if they are not
+          in one of the specified VLANs.  For this purpose, packets
+          that have no VLAN header are treated as part of VLAN 0.
+        </p>
       </column>
     </group>
 
@@ -227,17 +281,21 @@
       <column name="bond_downdelay">
         For a bonded port, the number of milliseconds for which carrier must
         stay down on an interface before the interface is considered to be
-        down.  Specify <code>0</code> to enable the interface immediately.
+        down.  Specify <code>0</code> to disable the interface immediately.
       </column>
 
       <column name="bond_fake_iface">
-        For a bonded port, whether to create a fake interface with the name of
-        the port.  Use only for compatibility with legacy software that
+        For a bonded port, whether to create a fake internal interface with the
+        name of the port.  Use only for compatibility with legacy software that
         requires this.
       </column>
     </group>
 
     <group title="Other Features">
+      <column name="qos">
+        Quality of Service configuration for this port.
+      </column>
+      
       <column name="mac">
         The MAC address to use for this port for the purpose of choosing the
         bridge's MAC address.  This column does not necessarily reflect the
@@ -254,9 +312,10 @@
         Key-value pairs that identify this port's role in external systems.  No
         key-value pairs native to <ref table="Port"/> are currently defined.
         For fake bridges (see the <ref column="fake_bridge"/> column), external
-        IDs for the fake bridge are defined here by prefixing their keys
+        IDs for the fake bridge are defined here by prefixing a
+        <ref table="Bridge"/> <ref table="Bridge" column="external_ids"/> key
         with <code>fake-bridge-</code>,
-        e.g. <code>fake-bridge-xs-network-uuids</code>.
+        e.g. <code>fake-bridge-network-uuids</code>.
       </column>
 
       <column name="other_config">
@@ -264,8 +323,15 @@
         currently defined key-value pairs are:
         <dl>
           <dt><code>hwaddr</code></dt>
-          <dd>Exactly 12 hex digits in the form
+          <dd>An Ethernet address in the form
             <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.</dd>
+          <dt><code>bond-rebalance-interval</code></dt>
+          <dd>For a 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.  The default is 10000 (10
+            seconds), and the minimum is 1000 (1 second).</dd>
         </dl>
       </column>
     </group>
@@ -293,7 +359,7 @@
             whose name is first in alphabetical order).  Internal ports and
             bridge ports that are used as port mirroring destinations (see the
             <ref table="Mirror"/> table) are ignored.</li>
-          <li>For other internal interface, the default MAC is randomly
+          <li>For other internal interfaces, the default MAC is randomly
             generated.</li>
           <li>External interfaces typically have a MAC address associated with
             their hardware.</li>
@@ -310,10 +376,10 @@
         <p>Open vSwitch populates this column when the port number becomes
           known.  If the interface is successfully added,
           <ref column="ofport"/> will be set to a number between 1 and 65535
-          (generally either in the range 1 to <code>0xff00</code>, exclusive,
-          or <code>0xfffe</code>, the port number for the OpenFlow ``local
-          port'').  If the interface cannot be added then Open vSwitch sets
-          this column to <code>-1</code>.</p>
+          (generally either in the range 1 to 65280, exclusive, or 65534, the
+          port number for the OpenFlow ``local port'').  If the interface
+          cannot be added then Open vSwitch sets this column
+          to -1.</p>
       </column>
     </group>
 
@@ -328,7 +394,7 @@
             vSwitch is running.  The empty string is a synonym for
             <code>system</code>.</dd>
           <dt><code>internal</code></dt>
-          <dd>A simulated network devices that sent and receive traffic.  An
+          <dd>A simulated network device that sends and receives traffic.  An
             internal interface whose <ref column="name"/> is the same as its
             bridge's <ref table="Open_vSwitch" column="name"/> is called the
             ``local interface.''  It does not make sense to bond an internal
@@ -337,7 +403,94 @@
           <dt><code>tap</code></dt>
           <dd>A TUN/TAP device managed by Open vSwitch.</dd>
           <dt><code>gre</code></dt>
-          <dd>A GRE tunnel device managed by Open vSwitch.</dd>
+          <dd>An Ethernet over RFC 1702 Generic Routing Encapsulation over IPv4
+             tunnel.  Each tunnel must be uniquely identified by the
+             combination of <code>remote_ip</code>, <code>local_ip</code>, and
+             <code>in_key</code>.  Note that if two ports are defined that are
+             the same except one has an optional identifier and the other does
+             not, the more specific one is matched first.  <code>in_key</code>
+             is considered more specific than <code>local_ip</code> if a port
+             defines one and another port defines the other.  The arguments
+             are:
+            <dl>
+              <dt><code>remote_ip</code></dt>
+              <dd>Required.  The tunnel endpoint.</dd>
+            </dl>
+            <dl>
+              <dt><code>local_ip</code></dt>
+              <dd>Optional.  The destination IP that received packets must
+                match.  Default is to match all addresses.</dd>
+            </dl>
+            <dl>
+              <dt><code>in_key</code></dt>
+              <dd>Optional.  The GRE key that received packets must contain.
+                It may either be a 32-bit number (no key and a key of 0 are
+                treated as equivalent) or the word <code>flow</code>.  If
+                <code>flow</code> is specified then any key will be accepted
+                and the key will be placed in the <code>tun_id</code> field
+                for matching in the flow table.  The ovs-ofctl manual page
+                contains additional information about matching fields in
+                OpenFlow flows.  Default is no key.</dd>
+            </dl>
+            <dl>
+              <dt><code>out_key</code></dt>
+              <dd>Optional.  The GRE key to be set on outgoing packets.  It may
+                either be a 32-bit number or the word <code>flow</code>.  If
+                <code>flow</code> is specified then the key may be set using
+                the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
+                is used in the absense of an action).  The ovs-ofctl manual
+                page contains additional information about the Nicira OpenFlow
+                vendor extensions.  Default is no key.</dd>
+            </dl>
+            <dl>
+              <dt><code>key</code></dt>
+              <dd>Optional.  Shorthand to set <code>in_key</code> and
+                <code>out_key</code> at the same time.</dd>
+            </dl>
+            <dl>
+              <dt><code>tos</code></dt>
+              <dd>Optional.  The value of the ToS bits to be set on the
+                encapsulating packet.  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).  Note that the ECN fields are always inherited.  Default is
+                0.</dd>
+            </dl>
+            <dl>
+              <dt><code>ttl</code></dt>
+              <dd>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.</dd>
+            </dl>
+            <dl>
+              <dt><code>csum</code></dt>
+              <dd>Optional.  Compute GRE checksums for outgoing packets and
+                require checksums for incoming packets.  Default is enabled,
+                set to <code>false</code> to disable.</dd>
+            </dl>
+            <dl>
+              <dt><code>pmtud</code></dt>
+              <dd>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.  It
+                also forces the encapsulating packet DF bit to be set (it is
+                always set if the inner packet implies path MTU discovery).
+                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 enabled, set to <code>false</code> to disable.</dd>
+            </dl>
+          </dd>
+          <dt><code>patch</code></dt>
+          <dd>A pair of virtual devices that act as a patch cable.  A 
+            <code>peer</code> argument is required that indicates the name
+            of the other side of the patch.  Since a patch must work in
+            pairs, a second patch interface must be declared with the
+            <code>name</code> and <code>peer</code> arguments reversed.</dd>
         </dl>
       </column>
 
@@ -371,26 +524,178 @@
 
     <group title="Other Features">
       <column name="external_ids">
-        Key-value pairs that identify this interface's role in external
-        systems.  The currently defined key-value pairs are:
+        <p>Key-value pairs that identify this interface's role in external
+          systems.  All of the currently defined 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 are:</p>
         <dl>
-          <dt><code>xs-vif-uuid</code></dt>
-          <dd>UUID of the Citrix XenServer VIF associated with this
-            interface</dd>
-          <dt><code>xs-network-uuid</code></dt>
-          <dd>UUID of the Citrix XenServer network to which this interface is
-            attached</dd>
-          <dt><code>xs-vif-vm-uuid</code></dt>
-          <dd>UUID of the Citrix XenServer VM to which this interface
-            belongs</dd>
-          <dt><code>xs-vif-mac</code></dt>
-          <dd>The value of the "MAC" field in the Citrix XenServer VIF record
-            for this interface.</dd>
+          <dt><code>vif-uuid</code></dt>
+          <dd>The virtual interface associated with this interface.</dd>
+          <dt><code>network-uuid</code></dt>
+          <dd>The virtual network to which this interface is attached.</dd>
+          <dt><code>vm-uuid</code></dt>
+          <dd>The VM to which this interface belongs.</dd>
+          <dt><code>vif-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>
         </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.</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> class supports 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>
+  </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.</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>
+    </column>
+  </table>
+
   <table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
     <p>A port mirror within a <ref table="Bridge"/>.</p>
     <p>A port mirror configures a bridge to send selected frames to special
@@ -403,14 +708,17 @@
     </column>
 
     <group title="Selecting Packets for Mirroring">
+      <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.  If this
-        column and <ref column="select_dst_port"/> are both empty, then all
-        packets on all ports are selected for mirroring.
+        Ports on which arriving packets are selected for mirroring.
       </column>
 
       <column name="select_vlan">
@@ -470,13 +778,20 @@
   </table>
 
   <table name="Controller" title="OpenFlow controller configuration.">
-    An OpenFlow controller.
+    <p>An OpenFlow controller.</p>
+
+    <p>Open vSwitch permits a bridge to have any number of OpenFlow
+       controllers.  When multiple controllers are configured, Open vSwitch
+       connects to all of them simultaneously.  OpenFlow 1.0 does not specify
+       how multiple controllers coordinate in interacting with a single switch,
+       so more than one controller should be specified only if the controllers
+       are themselves designed to coordinate with each other.</p>
 
     <group title="Core Features">
       <column name="target">
-        Connection method for controller.
-        The following connection methods are currently
-        supported:
+        <p>Connection method for controller.
+          The following connection methods are currently
+          supported:</p>
         <dl>
           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
           <dd>
@@ -493,15 +808,58 @@
             the given <var>ip</var>, which must be expressed as an IP address
             (not a DNS name).</dd>
           <dt><code>discover</code></dt>
-          <dd>Enables controller discovery.</dd>
+          <dd>
+            <p>Enables controller discovery.</p>
+            <p>In controller discovery mode, Open vSwitch broadcasts a DHCP
+              request with vendor class identifier <code>OpenFlow</code> across
+              all of the bridge's network devices.  It will accept any valid
+              DHCP reply that has the same vendor class identifier and includes
+              a vendor-specific option with code 1 whose contents are a string
+              specifying the location of the controller in the same format as
+              <ref column="target"/>.</p>
+            <p>The DHCP reply may also, optionally, include a vendor-specific
+              option with code 2 whose contents are a string specifying the URI
+              to the base of the OpenFlow PKI
+              (e.g. <code>http://192.168.0.1/openflow/pki</code>).  This URI is
+              used only for bootstrapping the OpenFlow PKI at initial switch
+              setup; <code>ovs-vswitchd</code> does not use it at all.</p>
+          </dd>
           <dt><code>none</code></dt>
           <dd>Disables the controller.</dd>
         </dl>
+	<p>When multiple controllers are configured for a single bridge, the
+	  <ref column="target"/> values must be unique.  Duplicate
+	  <ref column="target"/> values yield unspecified results.</p>
       </column>
 
       <column name="connection_mode">
-        Either <code>in-band</code> or <code>out-of-band</code>.  If not
-        specified, the default is implementation-specific.
+	<p>If it is specified, this setting must be one of the following
+	strings that describes how Open vSwitch contacts this OpenFlow
+	controller over the network:</p>
+
+	<dl>
+	  <dt><code>in-band</code></dt>
+	  <dd>In this mode, this controller's OpenFlow traffic travels over the
+	    bridge associated with the controller.  With this setting, Open
+	    vSwitch allows traffic to and from the controller regardless of the
+	    contents of the OpenFlow flow table.  (Otherwise, Open vSwitch
+	    would never be able to connect to the controller, because it did
+	    not have a flow to enable it.)  This is the most common connection
+	    mode because it is not necessary to maintain two independent
+	    networks.</dd>
+	  <dt><code>out-of-band</code></dt>
+	  <dd>In this mode, OpenFlow traffic uses a control network separate
+	    from the bridge associated with this controller, that is, the
+	    bridge does not use any of its own network devices to communicate
+	    with the controller.  The control network must be configured
+	    separately, before or after <code>ovs-vswitchd</code> is started.
+	  </dd>
+	</dl>
+
+        <p>If not specified, the default is implementation-specific.  If
+          <ref column="target"/> is <code>discover</code>, the connection mode
+          is always treated as <code>in-band</code> regardless of the actual
+          setting.</p>
       </column>
     </group>
 
@@ -535,7 +893,7 @@
               times the inactivity probe interval
               (see <ref column="inactivity_probe"/>), then Open vSwitch
               will take over responsibility for setting up flows.  In
-              this mode, Open vSwitch causes the datapath to act like an
+              this mode, Open vSwitch causes the bridge to act like an
               ordinary MAC-learning switch.  Open vSwitch will continue
               to retry connecting to the controller in the background
               and, when the connection succeeds, it will discontinue its
@@ -546,19 +904,20 @@
               connecting to the controller forever.</dd>
           </dl>
         </p>
-        <p>If this value is unset, the default is
-        implementation-specific.</p>
+        <p>If this value is unset, the default is implementation-specific.</p>
+	<p>When more than one controller is configured,
+	  <ref column="fail_mode"/> is considered only when none of the
+	  configured controllers can be contacted.  At that point, the bridge
+	  enters secure mode if any of the controllers'
+	  <ref column="fail_mode"/> is set to <code>secure</code>.  Otherwise,
+	  it enters standalone mode if at least one <ref column="fail_mode"/>
+	  is set to <code>standalone</code>.  If none of the
+	  <ref column="fail_mode"/> values are set, the default is
+	  implementation-defined.</p>
       </column>
     </group>
 
     <group title="OpenFlow Rate Limiting">
-        <column name="controller_burst_limit">
-          In conjunction with <ref column="controller_rate_limit"/>,
-          the maximum number of unused packet credits that the bridge will
-          allow to accumulate, in packets.  If not specified, the default
-          is implementation-specific.
-        </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
@@ -578,11 +937,21 @@
             actual rate that packets are sent to the controller is up to
             twice the specified rate.</p>
         </column>
+
+        <column name="controller_burst_limit">
+          In conjunction with <ref column="controller_rate_limit"/>,
+          the maximum number of unused packet credits that the bridge will
+          allow to accumulate, in packets.  If not specified, the default
+          is implementation-specific.
+        </column>
     </group>
 
-    <group title="Additional Configuration for Discovery">
+    <group title="Additional Discovery Configuration">
+      <p>These values are considered only when <ref column="target"/>
+	is <code>discover</code>.</p>
+
       <column name="discover_accept_regex">
-        If <ref column="target"/> is <code>discover</code>, a POSIX
+        A POSIX
         extended regular expression against which the discovered controller
         location is validated.  The regular expression is implicitly
         anchored at the beginning of the controller location string, as
@@ -591,8 +960,7 @@
       </column>
 
       <column name="discover_update_resolv_conf">
-        If <ref column="target"/> is <code>discover</code>,
-        whether to update <code>/etc/resolv.conf</code> when the
+        Whether to update <code>/etc/resolv.conf</code> when the
         controller is discovered.  If not specified, the default
         is implementation-specific.  Open vSwitch will only modify
         <code>/etc/resolv.conf</code> if the DHCP response that it receives
@@ -600,20 +968,35 @@
       </column>
     </group>
 
-    <group title="Additional Configuration without Discovery">
-      <column name="local_gateway">
-        If <ref column="target"/> is not <code>discover</code>, the IP
-        address of the gateway to configure on the local port.
-      </column>
+    <group title="Additional In-Band Configuration">
+      <p>These values are considered only in in-band control mode (see
+	<ref column="connection_mode"/>) and only when <ref column="target"/>
+	is not <code>discover</code>.  (For controller discovery, the network
+	configuration obtained via DHCP is used instead.)</p>
+
+      <p>When multiple controllers are configured on a single bridge, there
+	should be only one set of unique values in these columns.  If different
+	values are set for these columns in different controllers, the effect
+	is unspecified.</p>
 
       <column name="local_ip">
-        If <ref column="target"/> is not <code>discover</code>, the IP
-        address to configure on the local port.
+        The IP address to configure on the local port,
+        e.g. <code>192.168.0.123</code>.  If this value is unset, then
+        <ref column="local_netmask"/> and <ref column="local_gateway"/> are
+        ignored.
       </column>
 
       <column name="local_netmask">
-        If <ref column="target"/> is not <code>discover</code>, the IP
-        netmask to configure on the local port.
+        The IP netmask to configure on the local port,
+        e.g. <code>255.255.255.0</code>.  If <ref column="local_ip"/> is set
+        but this value is unset, then the default is chosen based on whether
+        the IP address is class A, B, or C.
+      </column>
+
+      <column name="local_gateway">
+        The IP address of the gateway to configure on the local port, as a
+        string, e.g. <code>192.168.0.1</code>.  Leave this column unset if
+        this network has no gateway.
       </column>
     </group>
   </table>
@@ -696,10 +1079,11 @@
       of switches.</p>
 
     <column name="agent">
-      IP address to report as ``agent address'' to collectors.  If not
-      specified, defaults to the <ref table="Controller" column="local_ip"/> in
-      the collector's <ref table="Controller"/>.  If neither is specified,
-      sFlow is disabled.
+      Name of the network device whose IP address should be reported as the
+      ``agent address'' to collectors.  If not specified, 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.
     </column>
 
     <column name="header">
@@ -723,4 +1107,46 @@
       <code><var>ip</var>:<var>port</var></code>.
     </column>
   </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>