X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=vswitchd%2Fvswitch.xml;h=345744e6d7a3936ed64696d7085320d23b4acc9b;hb=9575eae3724fb437b2df9bfad02501325d3dcdaf;hp=2aba34fdf4f1840d4db4c3635c2477586832893d;hpb=8872051980d541cd7b88c624ac3a08e85171df40;p=openvswitch

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index 2aba34fd..345744e6 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -16,7 +16,7 @@
       </column>
 
       <column name="controller">
-        Default <ref table="Controller"/> used by bridges.  May be
+        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>
@@ -104,10 +104,11 @@
 
     <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">
@@ -587,13 +588,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>
@@ -610,15 +618,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>
 
@@ -652,7 +703,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
@@ -663,19 +714,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
@@ -695,11 +747,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
@@ -708,8 +770,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
@@ -717,20 +778,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>
@@ -813,10 +889,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">