[ovs-dev] [PATCH] Document GRE port options.

[Jesse Gross]

---
 vswitchd/vswitch.xml |   78 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 77 insertions(+), 1 deletions(-)

diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml
index e1019e2..803b33c 100644
--- a/vswitchd/vswitch.xml
+++ b/vswitchd/vswitch.xml
@@ -356,7 +356,83 @@
           <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>Ethernet over GRE 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.  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).  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
-- 
1.6.3.3