X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=vswitchd%2Fvswitch.xml;h=5bbe943f20b3e0306ae59e39012683caf64cd40e;hb=448a4b2fc74b9d3884f3702c4b8801eb0d443f10;hp=21bcbc2e5d92f2276eb7d785868fc83db122dbb1;hpb=798e1352d09bc48d1eecb6ecf1b2c21d9b1ba2a5;p=sliver-openvswitch.git

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index 21bcbc2e5..5bbe943f2 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -71,6 +71,109 @@
         The Citrix XenServer universally unique identifier for the physical
         host as displayed by <code>xe host-list</code>.
       </column>
+
+      <column name="other_config" key="flow-restore-wait"
+              type='{"type": "boolean"}'>
+        <p>
+          When <code>ovs-vswitchd</code> starts up, it has an empty flow table
+          and therefore it handles all arriving packets in its default fashion
+          according to its configuration, by dropping them or sending them to
+          an OpenFlow controller or switching them as a standalone switch.
+          This behavior is ordinarily desirable.  However, if
+          <code>ovs-vswitchd</code> is restarting as part of a ``hot-upgrade,''
+          then this leads to a relatively long period during which packets are
+          mishandled.
+        </p>
+        <p>
+          This option allows for improvement.  When <code>ovs-vswitchd</code>
+          starts with this value set as <code>true</code>, it will neither
+          flush or expire previously set datapath flows nor will it send and
+          receive any packets to or from the datapath.  When this value is
+          later set to <code>false</code>, <code>ovs-vswitchd</code> will
+          start receiving packets from the datapath and re-setup the flows.
+        </p>
+        <p>
+          Thus, with this option, the procedure for a hot-upgrade of
+          <code>ovs-vswitchd</code> becomes roughly the following:
+        </p>
+        <ol>
+          <li>
+            Stop <code>ovs-vswitchd</code>.
+          </li>
+          <li>
+            Set <ref column="other_config" key="flow-restore-wait"/>
+            to <code>true</code>.
+          </li>
+          <li>
+            Start <code>ovs-vswitchd</code>.
+          </li>
+          <li>
+            Use <code>ovs-ofctl</code> (or some other program, such as an
+            OpenFlow controller) to restore the OpenFlow flow table
+            to the desired state.
+          </li>
+          <li>
+            Set <ref column="other_config" key="flow-restore-wait"/>
+            to <code>false</code> (or remove it entirely from the database).
+          </li>
+        </ol>
+        <p>
+          The <code>ovs-ctl</code>'s ``restart'' and ``force-reload-kmod''
+          functions use the above config option during hot upgrades.
+        </p>
+      </column>
+
+      <column name="other_config" key="flow-eviction-threshold"
+              type='{"type": "integer", "minInteger": 0}'>
+        <p>
+          A number of flows as a nonnegative integer.  This sets number of
+          flows at which eviction from the datapath flow table will be
+          triggered.  If there are a large number of flows then increasing this
+          value to around the number of flows present can result in reduced CPU
+          usage and packet loss.
+        </p>
+        <p>
+          The default is 2500.  Values below 100 will be rounded up to 100.
+        </p>
+      </column>
+
+      <column name="other_config" key="force-miss-model">
+        <p>
+          Specifies userspace behaviour for handling flow misses. This takes
+          precedence over flow-eviction-threshold.
+        </p>
+        <p>
+          <dl>
+            <dt><code>auto</code></dt>
+            <dd>Handle automatically based on the flow-eviction-threshold and
+            the flow setup governer (default, recommended).</dd>
+            <dt><code>with-facets</code></dt>
+            <dd>Always create facets. Expensive kernel flow creation and
+            statistics tracking is always performed, even on flows with only
+            a small number of packets.</dd>
+            <dt><code>without-facets</code></dt>
+            <dd>Always handle without facets. Forces flow misses to be handled
+            in userspace. May cause an increase in CPU usage and packet loss
+            on high throughput.</dd>
+          </dl>
+        </p>
+      </column>
+
+      <column name="other_config" key="n-handler-threads"
+              type='{"type": "integer", "minInteger": 1}'>
+        <p>
+          Specifies the number of threads for software datapaths to use for
+          handling new flows.  The default is one less than the number of
+          online CPU cores (but at least 1).
+        </p>
+        <p>
+          This configuration is per datapath.  If you have more than one
+          software datapath (e.g. some <code>system</code> bridges and some
+          <code>netdev</code> bridges), then the total number of threads is
+          <code>n-handler-threads</code> times the number of software
+          datapaths.
+        </p>
+      </column>
     </group>
 
     <group title="Status">
@@ -340,7 +443,11 @@
       </column>
 
       <column name="sflow">
-        sFlow configuration.
+        sFlow(R) configuration.
+      </column>
+
+      <column name="ipfix">
+        IPFIX configuration.
       </column>
 
       <column name="flood_vlans">
@@ -543,20 +650,6 @@
         datapath ID.
       </column>
 
-      <column name="other_config" key="flow-eviction-threshold"
-              type='{"type": "integer", "minInteger": 0}'>
-        <p>
-          A number of flows as a nonnegative integer.  This sets number of
-          flows at which eviction from the kernel flow table will be triggered.
-          If there are a large number of flows then increasing this value to
-          around the number of flows present can result in reduced CPU usage
-          and packet loss.
-        </p>
-        <p>
-          The default is 1000.  Values below 100 will be rounded up to 100.
-        </p>
-      </column>
-
       <column name="other_config" key="forward-bpdu"
               type='{"type": "boolean"}'>
         Option to allow forwarding of BPDU frames when NORMAL action is
@@ -1131,6 +1224,12 @@
         on a host.
       </column>
 
+      <column name="ifindex">
+        A positive interface index as defined for SNMP MIB-II in RFCs 1213 and
+        2863, if the interface has one, otherwise 0.  The ifindex is useful for
+        seamless integration with protocols such as SNMP and sFlow.
+      </column>
+
       <column name="mac_in_use">
         The MAC address in use by this interface.
       </column>
@@ -1246,10 +1345,9 @@
 	      with kernel version 2.6.26 or later.
 	    </p>
 	    <p>
-	      As an experimental protocol, VXLAN has no officially assigned UDP
-	      port.  Open vSwitch currently uses UDP destination port 8472.
-	      The source port used for VXLAN traffic varies on a per-flow basis
-	      and is in the ephemeral port range.
+	      Open vSwitch uses UDP destination port 4789.  The source port used for
+	      VXLAN traffic varies on a per-flow basis and is in the ephemeral port
+	      range.
 	    </p>
           </dd>
 
@@ -1291,12 +1389,67 @@
       </p>
 
       <column name="options" key="remote_ip">
-          Required.  The tunnel endpoint.  Only unicast endpoints are supported.
+        <p>Required.  The remote tunnel endpoint, one of:</p>
+
+        <ul>
+          <li>
+            An IPv4 address (not a DNS name), e.g. <code>192.168.0.123</code>.
+            Only unicast endpoints are supported.
+          </li>
+          <li>
+            The word <code>flow</code>.  The tunnel accepts packets from any
+            remote tunnel endpoint.  To process only packets from a specific
+            remote tunnel endpoint, the flow entries may match on the
+            <code>tun_src</code> field.  When sending packets to a
+            <code>remote_ip=flow</code> tunnel, the flow actions must
+            explicitly set the <code>tun_dst</code> field to the IP address of
+            the desired remote tunnel endpoint, e.g. with a
+            <code>set_field</code> action.
+          </li>
+        </ul>
+
+        <p>
+         The remote tunnel endpoint for any packet received from a tunnel
+         is available in the <code>tun_src</code> field for matching in the
+         flow table.
+        </p>
       </column>
 
       <column name="options" key="local_ip">
-        Optional.  The destination IP that received packets must match.
-        Default is to match all addresses.
+        <p>
+          Optional.  The tunnel destination IP that received packets must
+          match.  Default is to match all addresses.  If specified, may be one
+          of:
+        </p>
+
+        <ul>
+          <li>
+            An IPv4 address (not a DNS name), e.g. <code>192.168.12.3</code>.
+          </li>
+          <li>
+            The word <code>flow</code>.  The tunnel accepts packets sent to any
+            of the local IP addresses of the system running OVS.  To process
+            only packets sent to a specific IP address, the flow entries may
+            match on the <code>tun_dst</code> field.  When sending packets to a
+            <code>local_ip=flow</code> tunnel, the flow actions may
+            explicitly set the <code>tun_src</code> field to the desired IP
+            address, e.g. with a <code>set_field</code> action.  However, while
+            routing the tunneled packet out, the local system may override the
+            specified address with the local IP address configured for the
+            outgoing system interface.
+
+            <p>
+              This option is valid only for tunnels also configured with the
+              <code>remote_ip=flow</code> option.
+            </p>
+          </li>
+        </ul>
+
+        <p>
+          The tunnel destination IP address for any packet received from a
+          tunnel is available in the <code>tun_dst</code> field for matching in
+          the flow table.
+        </p>
       </column>
 
       <column name="options" key="in_key">
@@ -1692,6 +1845,113 @@
       </column>
     </group>
 
+    <group title="Bidirectional Forwarding Detection (BFD)">
+        <p>
+            BFD, defined in RFC 5880 and RFC 5881, allows point to point
+            detection of connectivity failures by occasional transmission of
+            BFD control messages.  It is implemented in Open vSwitch to serve
+            as a more popular and standards compliant alternative to CFM.
+        </p>
+
+        <p>
+            BFD operates by regularly transmitting BFD control messages at a
+            rate negotiated independently in each direction.  Each endpoint
+            specifies the rate at which it expects to receive control messages,
+            and the rate at which it's willing to transmit them.  Open vSwitch
+            uses a detection multiplier of three, meaning that an endpoint
+            which fails to receive BFD control messages for a period of three
+            times the expected reception rate, will signal a connectivity
+            fault.  In the case of a unidirectional connectivity issue, the
+            system not receiving BFD control messages will signal the problem
+            to its peer in the messages it transmits.
+        </p>
+
+        <p>
+            The Open vSwitch implementation of BFD aims to comply faithfully
+            with the requirements put forth in RFC 5880.  Currently, the only
+            known omission is ``Demand Mode'', which we hope to include in
+            future.  Open vSwitch does not implement the optional
+            Authentication or ``Echo Mode'' features.
+        </p>
+
+      <column name="bfd" key="enable">
+          When <code>true</code> BFD is enabled on this
+          <ref table="Interface"/>, otherwise it's disabled.  Defaults to
+          <code>false</code>.
+      </column>
+
+      <column name="bfd" key="min_rx"
+          type='{"type": "integer", "minInteger": 1}'>
+          The fastest rate, in milliseconds, at which this BFD session is
+          willing to receive BFD control messages.  The actual rate may be
+          slower if the remote endpoint isn't willing to transmit as quickly as
+          specified.  Defaults to <code>1000</code>.
+      </column>
+
+      <column name="bfd" key="min_tx"
+          type='{"type": "integer", "minInteger": 1}'>
+          The fastest rate, in milliseconds, at which this BFD session is
+          willing to transmit BFD control messages.  The actual rate may be
+          slower if the remote endpoint isn't willing to receive as quickly as
+          specified.  Defaults to <code>100</code>.
+      </column>
+
+      <column name="bfd" key="cpath_down" type='{"type": "boolean"}'>
+          Concatenated path down may be used when the local system should not
+          have traffic forwarded to it for some reason other than a connectivty
+          failure on the interface being monitored.  When a controller thinks
+          this may be the case, it may set <code>cpath_down</code> to
+          <code>true</code> which may cause the remote BFD session not to
+          forward traffic to this <ref table="Interface"/>. Defaults to
+          <code>false</code>.
+      </column>
+
+      <column name="bfd" key="check_tnl_key" type='{"type": "boolean"}'>
+          When set to true, Check Tunnel Key will make BFD only accept control
+          messages with an <code>in_key</code> of zero. Defaults to
+          <code>false</code>.
+      </column>
+
+      <column name="bfd" key="bfd_dst_mac">
+        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 destination mac address of the bfd packet. If this
+        field is set, it is assumed that all the bfd packets destined to this
+        interface also has the same destination mac address. If not set, a
+        default value of <code>00:23:20:00:00:01</code> is used.
+      </column>
+
+      <column name="bfd_status" key="state"
+          type='{"type": "string",
+          "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
+          State of the BFD session.  The BFD session is fully healthy and
+          negotiated if <code>UP</code>.
+      </column>
+
+      <column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
+          True if the BFD session believes this <ref table="Interface"/> may be
+          used to forward traffic.  Typically this means the local session is
+          signaling <code>UP</code>, and the remote system isn't signaling a
+          problem such as concatenated path down.
+      </column>
+
+      <column name="bfd_status" key="diagnostic">
+          A short message indicating what the BFD session thinks is wrong in
+          case of a problem.
+      </column>
+
+      <column name="bfd_status" key="remote_state"
+          type='{"type": "string",
+          "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
+          State of the remote endpoint's BFD session.
+      </column>
+
+      <column name="bfd_status" key="remote_diagnostic">
+          A short message indicating what the remote endpoint's BFD session
+          thinks is wrong in case of a problem.
+      </column>
+    </group>
+
     <group title="Connectivity Fault Management">
       <p>
         802.1ag Connectivity Fault Management (CFM) allows a group of
@@ -1850,6 +2110,43 @@
         compatibility with 802.1ag compliant implementations.  Defaults to
         <code>false</code>.
       </column>
+
+      <column name="other_config" key="cfm_demand" type='{"type": "boolean"}'>
+        <p>
+          When <code>true</code>, and
+          <ref column="other_config" key="cfm_extended"/> is true, the CFM
+          module operates in demand mode.  When in demand mode, traffic
+          received on the <ref table="Interface"/> is used to indicate
+          liveness.  CCMs are still transmitted and received, but if the
+          <ref table="Interface"/> is receiving traffic, their absence does not
+          cause a connectivity fault.
+        </p>
+
+        <p>
+            Demand mode has a couple of caveats:
+          <ul>
+            <li>
+              To ensure that ovs-vswitchd has enough time to pull statistics
+              from the datapath, the minimum
+              <ref column="other_config" key="cfm_interval"/> is 500ms.
+            </li>
+
+            <li>
+              To avoid ambiguity, demand mode disables itself when there are
+              multiple remote maintenance points.
+            </li>
+
+            <li>
+              If the <ref table="Interface"/> is heavily congested, CCMs
+              containing the <ref column="other_config" key="cfm_opstate"/>
+              status may be dropped causing changes in the operational state to
+              be delayed.  Similarly, if CCMs containing the RDI bit are not
+              received, unidirectional link failures may not be detected.
+            </li>
+          </ul>
+        </p>
+      </column>
+
       <column name="other_config" key="cfm_opstate"
               type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
         When <code>down</code>, the CFM module marks all CCMs it generates as
@@ -3129,8 +3426,8 @@
   </table>
 
   <table name="sFlow">
-    <p>An sFlow(R) target.  sFlow is a protocol for remote monitoring
-    of switches.</p>
+    <p>A set of sFlow(R) targets.  sFlow is a protocol for remote
+    monitoring of switches.</p>
 
     <column name="agent">
       Name of the network device whose IP address should be reported as the
@@ -3171,4 +3468,75 @@
     </group>
   </table>
 
+  <table name="IPFIX">
+    <p>A set of IPFIX collectors.  IPFIX is a protocol that exports a
+    number of details about flows.</p>
+
+    <column name="targets">
+      IPFIX target collectors in the form
+      <code><var>ip</var>:<var>port</var></code>.
+    </column>
+
+    <column name="sampling">
+      For per-bridge packet sampling, i.e. when this row is referenced
+      from a <ref table="Bridge"/>, the rate at which packets should
+      be sampled and sent to each target collector.  If not specified,
+      defaults to 400, which means one out of 400 packets, on average,
+      will be sent to each target collector.  Ignored for per-flow
+      sampling, i.e. when this row is referenced from a <ref
+      table="Flow_Sample_Collector_Set"/>.
+    </column>
+
+    <column name="obs_domain_id">
+      For per-bridge packet sampling, i.e. when this row is referenced
+      from a <ref table="Bridge"/>, the IPFIX Observation Domain ID
+      sent in each IPFIX packet.  If not specified, defaults to 0.
+      Ignored for per-flow sampling, i.e. when this row is referenced
+      from a <ref table="Flow_Sample_Collector_Set"/>.
+    </column>
+
+    <column name="obs_point_id">
+      For per-bridge packet sampling, i.e. when this row is referenced
+      from a <ref table="Bridge"/>, the IPFIX Observation Point ID
+      sent in each IPFIX flow record.  If not specified, defaults to
+      0.  Ignored for per-flow sampling, i.e. when this row is
+      referenced from a <ref table="Flow_Sample_Collector_Set"/>.
+    </column>
+
+    <group title="Common Columns">
+      The overall purpose of these columns is described under <code>Common
+      Columns</code> at the beginning of this document.
+
+      <column name="external_ids"/>
+    </group>
+  </table>
+
+  <table name="Flow_Sample_Collector_Set">
+    <p>A set of IPFIX collectors of packet samples generated by
+    OpenFlow <code>sample</code> actions.</p>
+
+    <column name="id">
+      The ID of this collector set, unique among the bridge's
+      collector sets, to be used as the <code>collector_set_id</code>
+      in OpenFlow <code>sample</code> actions.
+    </column>
+
+    <column name="bridge">
+      The bridge into which OpenFlow <code>sample</code> actions can
+      be added to send packet samples to this set of IPFIX collectors.
+    </column>
+
+    <column name="ipfix">
+      Configuration of the set of IPFIX collectors to send one flow
+      record per sampled packet to.
+    </column>
+
+    <group title="Common Columns">
+      The overall purpose of these columns is described under <code>Common
+      Columns</code> at the beginning of this document.
+
+      <column name="external_ids"/>
+    </group>
+  </table>
+
 </database>