X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;ds=sidebyside;f=vswitchd%2Fvswitch.xml;h=465f27dd1b2a0df279f98a42f45298f687f82ad8;hb=142181fcd734a2afff9fe13e54fe51c7a2c824d2;hp=f5e010ba6ea559cc954e07ccfa1029acb97e598d;hpb=31681a5d627cec70864764586829bdb92abf2f30;p=openvswitch

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index f5e010ba..465f27dd 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -25,8 +25,12 @@
       </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:
+        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>system-uuid</code></dt>
           <dd>A universally unique identifier for the Open vSwitch's
@@ -151,8 +155,9 @@
               standalone behavior.</dd>
             <dt><code>secure</code></dt>
             <dd>Open vSwitch will not set up flows on its own when the
-              controller connection fails.  It will continue retry
-              connecting to the controller forever.</dd>
+              controller connection fails or when no controllers are
+              defined.  The bridge will continue to retry connecting to
+              any defined controllers forever.</dd>
           </dl>
         </p>
         <p>If this value is unset, the default is implementation-specific.</p>
@@ -177,8 +182,12 @@
       </column>
 
       <column name="external_ids">
-        Key-value pairs that identify this bridge's role in external systems.
-        The currently defined key-value pairs are:
+        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>network-uuids</code></dt>
           <dd>Semicolon-delimited set of universally unique identifier(s) for
@@ -331,13 +340,21 @@
       </column>
 
       <column name="external_ids">
-        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 a
-        <ref table="Bridge"/> <ref table="Bridge" column="external_ids"/> key
-        with <code>fake-bridge-</code>,
-        e.g. <code>fake-bridge-network-uuids</code>.
+        <p>
+          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.
+        </p>
+        <p>
+          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 a <ref table="Bridge"/> <ref table="Bridge"
+          column="external_ids"/> key with <code>fake-bridge-</code>,
+          e.g. <code>fake-bridge-network-uuids</code>.
+        </p>
       </column>
 
       <column name="other_config">
@@ -432,8 +449,8 @@
              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:
+             defines one and another port defines the other.  The following 
+             options may be specified in the <ref column="options"/> column:
             <dl>
               <dt><code>remote_ip</code></dt>
               <dd>Required.  The tunnel endpoint.</dd>
@@ -508,11 +525,23 @@
             </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>
+          <dd>
+            <p>
+              A pair of virtual devices that act as a patch cable.  The <ref
+              column="options"/> column must have the following key-value pair:
+            </p>
+            <dl>
+              <dt><code>peer</code></dt>
+              <dd>
+                The <ref column="name"/> of the <ref table="Interface"/> for
+                the other side of the patch.  The named <ref
+                table="Interface"/>'s own <code>peer</code> option must specify
+                this <ref table="Interface"/>'s name.  That is, the two patch
+                interfaces must have reversed <ref column="name"/> and
+                <code>peer</code> values.
+              </dd>
+            </dl>
+          </dd>
         </dl>
       </column>
 
@@ -546,15 +575,23 @@
 
     <group title="Other Features">
       <column name="external_ids">
-        <p>Key-value pairs that identify this interface's role in external
-          systems.  All of the currently defined key-value pairs specifically
+        <p>
+          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.
+        </p>
+        <p>
+          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>
+          formats.
+        </p>
         <p>The currently defined key-value pairs are:</p>
         <dl>
           <dt><code>vif-uuid</code></dt>
@@ -675,6 +712,14 @@
           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.">
@@ -716,6 +761,14 @@
           values are unimportant; only relative ordering matters.</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="Mirror" title="Port mirroring (SPAN/RSPAN).">
@@ -797,31 +850,95 @@
           in the appropriate <ref table="Bridge"/> table or tables.</p>
       </column>
     </group>
+
+    <group title="Other Features">
+      <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>
+    </group>
   </table>
 
   <table name="Controller" title="OpenFlow controller configuration.">
     <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>
+    <p>
+      Open vSwitch supports two kinds of OpenFlow controllers:
+    </p>
+    
+    <dl>
+      <dt>Primary controllers</dt>
+      <dd>
+        <p>
+          This is the kind of controller envisioned by the OpenFlow 1.0
+          specification.  Usually, a primary controller implements a network
+          policy by taking charge of the switch's flow table.
+        </p>
+
+        <p>
+          Open vSwitch initiates and maintains persistent connections to
+          primary controllers, retrying the connection each time it fails or
+          drops.  The <ref table="Bridge" column="fail_mode"/> column in the
+          <ref table="Bridge"/> table applies to primary controllers.
+        </p>
+
+        <p>
+          Open vSwitch permits a bridge to have any number of primary
+          controllers.  When multiple controllers are configured, Open
+          vSwitch connects to all of them simultaneously.  Because
+          OpenFlow 1.0 does not specify how multiple controllers
+          coordinate in interacting with a single switch, more than
+          one primary controller should be specified only if the
+          controllers are themselves designed to coordinate with each
+          other.  (The Nicira-defined <code>NXT_ROLE</code> OpenFlow
+          vendor extension may be useful for this.)
+        </p>
+      </dd>
+      <dt>Service controllers</dt>
+      <dd>
+        <p>
+          These kinds of OpenFlow controller connections are intended for
+          occasional support and maintenance use, e.g. with
+          <code>ovs-ofctl</code>.  Usually a service controller connects only
+          briefly to inspect or modify some of a switch's state.
+        </p>
+
+        <p>
+          Open vSwitch listens for incoming connections from service
+          controllers.  The service controllers initiate and, if necessary,
+          maintain the connections from their end.  The <ref table="Bridge"
+          column="fail_mode"/> column in the <ref table="Bridge"/> table does
+          not apply to service controllers.
+        </p>
+
+        <p>
+          Open vSwitch supports configuring any number of service controllers.
+        </p>
+      </dd>
+    </dl>
+
+    <p>
+      The <ref column="target"/> determines the type of controller.
+    </p>
 
     <group title="Core Features">
       <column name="target">
-        <p>Connection method for controller.
-          The following connection methods are currently
-          supported:</p>
+        <p>Connection method for controller.</p>
+        <p>
+          The following connection methods are currently supported for primary
+          controllers:
+        </p>
         <dl>
           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
           <dd>
             <p>The specified SSL <var>port</var> (default: 6633) on the host at
-              the given <var>ip</var>, which must be expressed as an IP address
-              (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
-              column in the <ref table="Open_vSwitch"/> must point to a valid
-              SSL configuration when this form is used.</p>
+            the given <var>ip</var>, which must be expressed as an IP address
+            (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
+            column in the <ref table="Open_vSwitch"/> table must point to a
+            valid SSL configuration when this form is used.</p>
             <p>SSL support is an optional feature that is not always built as
               part of Open vSwitch.</p>
           </dd>
@@ -846,8 +963,35 @@
               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>
+          The following connection methods are currently supported for service
+          controllers:
+        </p>
+        <dl>
+          <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
+          <dd>
+            <p>
+              Listens for SSL connections on the specified TCP <var>port</var>
+              (default: 6633).  If <var>ip</var>, which must be expressed as an
+              IP address (not a DNS name), is specified, then connections are
+              restricted to the specified local IP address.
+            </p>
+            <p>
+              The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
+              table="Open_vSwitch"/> table must point to a valid SSL
+              configuration when this form is used.
+            </p>
+            <p>SSL support is an optional feature that is not always built as
+              part of Open vSwitch.</p>
+          </dd>
+          <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
+          <dd>
+            Listens for connections on the specified TCP <var>port</var>
+            (default: 6633).  If <var>ip</var>, which must be expressed as an
+            IP address (not a DNS name), is specified, then connections are
+            restricted to the specified local IP address.
+          </dd>
         </dl>
 	<p>When multiple controllers are configured for a single bridge, the
 	  <ref column="target"/> values must be unique.  Duplicate
@@ -984,6 +1128,16 @@
         this network has no gateway.
       </column>
     </group>
+
+    <group title="Other Features">
+      <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>
+    </group>
   </table>
 
   <table name="NetFlow">
@@ -1025,6 +1179,14 @@
         disambiguate the traffic.</p>
       <p>When this option is enabled, a maximum of 508 ports are supported.</p>
     </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="SSL">
@@ -1057,6 +1219,14 @@
         SSL connection to a man-in-the-middle attack obtaining the initial
         CA certificate.</em>  It may still be useful for bootstrapping.
     </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="sFlow">
@@ -1091,6 +1261,14 @@
       sFlow targets in the form
       <code><var>ip</var>:<var>port</var></code>.
     </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="Capability">