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

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index b21b5600..345744e6 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,7 +53,7 @@
 
       <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>
     </group>
@@ -93,14 +104,15 @@
 
     <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.
       </column>
     </group>
 
@@ -115,12 +127,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 +141,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 +157,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>
@@ -227,12 +239,12 @@
       <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>
@@ -254,9 +266,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 +277,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 +313,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 +330,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 +348,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 +357,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,21 +478,29 @@
 
     <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>
     </group>
@@ -403,14 +518,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 +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>
@@ -493,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>
 
@@ -535,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
@@ -546,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
@@ -578,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
@@ -591,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
@@ -600,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>
@@ -696,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">