[ovs-dev] [PATCH 09/15] doc: Convert README-lisp to rST

Stephen Finucane stephen at that.guru
Tue Oct 18 20:03:39 UTC 2016


Signed-off-by: Stephen Finucane <stephen at that.guru>
---
 Makefile.am     |   2 +-
 README-lisp.md  |  81 ----------------------------------------
 README-lisp.rst | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 114 insertions(+), 82 deletions(-)
 delete mode 100644 README-lisp.md
 create mode 100644 README-lisp.rst

diff --git a/Makefile.am b/Makefile.am
index 9be391b..42ad5d0 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -90,7 +90,7 @@ docs = \
 	OPENFLOW-1.1+.md \
 	PORTING.rst \
 	README.rst \
-	README-lisp.md \
+	README-lisp.rst \
 	README-native-tunneling.md \
 	REPORTING-BUGS.rst \
 	SECURITY.rst \
diff --git a/README-lisp.md b/README-lisp.md
deleted file mode 100644
index f1e1172..0000000
--- a/README-lisp.md
+++ /dev/null
@@ -1,81 +0,0 @@
-Using LISP tunneling
-====================
-
-LISP is a layer 3 tunneling mechanism, meaning that encapsulated packets do
-not carry Ethernet headers, and ARP requests shouldn't be sent over the
-tunnel.  Because of this, there are some additional steps required for setting
-up LISP tunnels in Open vSwitch, until support for L3 tunnels will improve.
-
-This guide assumes tunneling between two VMs connected to OVS bridges on
-different hypervisors reachable over IPv4.  Of course, more than one VM may be
-connected to any of the hypervisors, and a hypervisor may communicate with
-several different hypervisors over the same lisp tunneling interface.  A LISP
-"map-cache" can be implemented using flows, see example at the bottom of this
-file.
-
-There are several scenarios:
-
-  1) the VMs have IP addresses in the same subnet and the hypervisors are also
-     in a single subnet (although one different from the VM's);
-  2) the VMs have IP addresses in the same subnet but the hypervisors are
-     separated by a router;
-  3) the VMs are in different subnets.
-
-In cases 1) and 3) ARP resolution can work as normal: ARP traffic is
-configured not to go through the LISP tunnel.  For case 1) ARP is able to
-reach the other VM, if both OVS instances default to MAC address learning.
-Case 3) requires the hypervisor be configured as the default router for the
-VMs.
-
-In case 2) the VMs expect ARP replies from each other, but this is not
-possible over a layer 3 tunnel.  One solution is to have static MAC address
-entries preconfigured on the VMs (e.g., `arp -f /etc/ethers` on startup on
-Unix based VMs), or have the hypervisor do proxy ARP.  In this scenario, the
-eth0 interfaces need not be added to the br0 bridge in the examples below.
-
-On the receiving side, the packet arrives without the original MAC header.
-The LISP tunneling code attaches a header with harcoded source and destination
-MAC address 02:00:00:00:00:00.  This address has all bits set to 0, except the
-locally administered bit, in order to avoid potential collisions with existing
-allocations.  In order for packets to reach their intended destination, the
-destination MAC address needs to be rewritten.  This can be done using the
-flow table.
-
-See below for an example setup, and the associated flow rules to enable LISP
-tunneling.
-
-               +---+                               +---+
-               |VM1|                               |VM2|
-               +---+                               +---+
-                 |                                   |
-            +--[tap0]--+                       +--[tap0]---+
-            |          |                       |           |
-        [lisp0] OVS1 [eth0]-----------------[eth0] OVS2 [lisp0]
-            |          |                       |           |
-            +----------+                       +-----------+
-
-On each hypervisor, interfaces tap0, eth0, and lisp0 are added to a single
-bridge instance, and become numbered 1, 2, and 3 respectively:
-
-    ovs-vsctl add-br br0
-    ovs-vsctl add-port br0 tap0
-    ovs-vsctl add-port br0 eth0
-    ovs-vsctl add-port br0 lisp0 -- set Interface lisp0 type=lisp options:remote_ip=flow options:key=flow
-
-The last command sets up flow based tunneling on the lisp0 interface.  From
-the LISP point of view, this is like having the Tunnel Router map cache
-implemented as flow rules.
-
-Flows on br0 should be configured as follows:
-
-    priority=3,dl_dst=02:00:00:00:00:00,action=mod_dl_dst:<VMx_MAC>,output:1
-    priority=2,in_port=1,dl_type=0x0806,action=NORMAL
-    priority=1,in_port=1,dl_type=0x0800,vlan_tci=0,nw_src=<EID_prefix>,action=set_field:<OVSx_IP>->tun_dst,output:3
-    priority=0,action=NORMAL
-
-The third rule is like a map cache entry:  the <EID_prefix> specified by the
-nw_src match field is mapped to the RLOC <OVSx_IP>, which is set as the tunnel
-destination for this particular flow.
-
-Optionally, if you want to use Instance ID in a flow, you can add
-"set_tunnel:<IID>" to the action list.
diff --git a/README-lisp.rst b/README-lisp.rst
new file mode 100644
index 0000000..a65a694
--- /dev/null
+++ b/README-lisp.rst
@@ -0,0 +1,113 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+      Convention for heading levels in Open vSwitch documentation:
+
+      =======  Heading 0 (reserved for the title in a document)
+      -------  Heading 1
+      ~~~~~~~  Heading 2
+      +++++++  Heading 3
+      '''''''  Heading 4
+
+      Avoid deeper levels because they do not render well.
+
+====================
+Using LISP tunneling
+====================
+
+LISP is a layer 3 tunneling mechanism, meaning that encapsulated packets do not
+carry Ethernet headers, and ARP requests shouldn't be sent over the tunnel.
+Because of this, there are some additional steps required for setting up LISP
+tunnels in Open vSwitch, until support for L3 tunnels will improve.
+
+This guide assumes tunneling between two VMs connected to OVS bridges on
+different hypervisors reachable over IPv4.  Of course, more than one VM may be
+connected to any of the hypervisors, and a hypervisor may communicate with
+several different hypervisors over the same lisp tunneling interface.  A LISP
+"map-cache" can be implemented using flows, see example at the bottom of this
+file.
+
+There are several scenarios:
+
+1) the VMs have IP addresses in the same subnet and the hypervisors are also
+   in a single subnet (although one different from the VM's);
+2) the VMs have IP addresses in the same subnet but the hypervisors are
+   separated by a router;
+3) the VMs are in different subnets.
+
+In cases 1) and 3) ARP resolution can work as normal: ARP traffic is configured
+not to go through the LISP tunnel.  For case 1) ARP is able to reach the other
+VM, if both OVS instances default to MAC address learning.  Case 3) requires
+the hypervisor be configured as the default router for the VMs.
+
+In case 2) the VMs expect ARP replies from each other, but this is not possible
+over a layer 3 tunnel.  One solution is to have static MAC address entries
+preconfigured on the VMs (e.g., ``arp -f /etc/ethers`` on startup on Unix based
+VMs), or have the hypervisor do proxy ARP.  In this scenario, the eth0
+interfaces need not be added to the br0 bridge in the examples below.
+
+On the receiving side, the packet arrives without the original MAC header.  The
+LISP tunneling code attaches a header with harcoded source and destination MAC
+address ``02:00:00:00:00:00``.  This address has all bits set to 0, except the
+locally administered bit, in order to avoid potential collisions with existing
+allocations.  In order for packets to reach their intended destination, the
+destination MAC address needs to be rewritten.  This can be done using the flow
+table.
+
+See below for an example setup, and the associated flow rules to enable LISP
+tunneling.
+
+::
+
+    Diagram
+
+           +---+                               +---+
+           |VM1|                               |VM2|
+           +---+                               +---+
+             |                                   |
+        +--[tap0]--+                       +--[tap0]---+
+        |          |                       |           |
+    [lisp0] OVS1 [eth0]-----------------[eth0] OVS2 [lisp0]
+        |          |                       |           |
+        +----------+                       +-----------+
+
+On each hypervisor, interfaces tap0, eth0, and lisp0 are added to a single
+bridge instance, and become numbered 1, 2, and 3 respectively:
+
+::
+
+    $ ovs-vsctl add-br br0
+    $ ovs-vsctl add-port br0 tap0
+    $ ovs-vsctl add-port br0 eth0
+    $ ovs-vsctl add-port br0 lisp0 \
+      -- set Interface lisp0 type=lisp options:remote_ip=flow options:key=flow
+
+The last command sets up flow based tunneling on the lisp0 interface.  From
+the LISP point of view, this is like having the Tunnel Router map cache
+implemented as flow rules.
+
+Flows on br0 should be configured as follows:
+
+::
+
+    priority=3,dl_dst=02:00:00:00:00:00,action=mod_dl_dst:<VMx_MAC>,output:1
+    priority=2,in_port=1,dl_type=0x0806,action=NORMAL
+    priority=1,in_port=1,dl_type=0x0800,vlan_tci=0,nw_src=<EID_prefix>,action=set_field:<OVSx_IP>->tun_dst,output:3
+    priority=0,action=NORMAL
+
+The third rule is like a map cache entry: the ``<EID_prefix>`` specified by the
+``nw_src`` match field is mapped to the RLOC ``<OVSx_IP>``, which is set as the
+tunnel destination for this particular flow.
+
+Optionally, if you want to use Instance ID in a flow, you can add
+``set_tunnel:<IID>`` to the action list.
-- 
2.7.4




More information about the dev mailing list