doc: Convert README-native-tunneling to rST

Signed-off-by: Stephen Finucane <[email protected]>
Signed-off-by: Russell Bryant <[email protected]>

Makefile.am

@@ -92,7 +92,7 @@ docs = \
 	PORTING.rst \
 	README.rst \
 	README-lisp.rst \
-	README-native-tunneling.md \
+	README-native-tunneling.rst \
 	REPORTING-BUGS.rst \
 	SECURITY.rst \
 	WHY-OVS.rst

README-native-tunneling.rst

@@ -0,0 +1,176 @@
+..
+      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.
+
+==========================================
+Native Tunneling in Open vSwitch Userspace
+==========================================
+
+Open vSwitch supports tunneling in userspace. Tunneling is implemented in
+a platform-independent way.
+
+Setup
+-----
+
+Setup physical bridges for all physical interfaces. Create integration bridge.
+Add VXLAN port to int-bridge. Assign IP address to physical bridge where
+VXLAN traffic is expected.
+
+Example
+-------
+
+Connect to VXLAN tunnel endpoint logical IP: ``192.168.1.2`` and
+``192.168.1.1``.
+
+Configure OVS bridges as follows.
+
+1. Let's assume ``172.168.1.2/24`` network is reachable via ``eth1``. Create
+   physical bridge ``br-eth1``. Assign IP address (``172.168.1.1/24``) to
+   ``br-eth1``. Add ``eth1`` to ``br-eth1``.
+
+2. Check ovs cached routes using appctl command.
+
+   ::
+
+       $ ovs-appctl ovs/route/show
+
+   Add tunnel route if not present in OVS route table.
+
+   ::
+
+       $ ovs-appctl ovs/route/add 172.168.1.1/24 br-eth1
+
+3. Add integration bridge ``int-br`` and add tunnel port using standard syntax.
+
+   ::
+
+       $ ovs-vsctl add-port int-br vxlan0 \
+         -- set interface vxlan0 type=vxlan options:remote_ip=172.168.1.2
+
+4. Assign IP address to ``int-br``.
+
+The final topology should looks like so:
+
+::
+
+    Diagram
+
+     192.168.1.1/24
+    +--------------+
+    |    int-br    |                                    192.168.1.2/24
+    +--------------+                                   +--------------+
+    |    vxlan0    |                                   |    vxlan0    |
+    +--------------+                                   +--------------+
+           |                                                  |
+           |                                                  |
+           |                                                  |
+     172.168.1.1/24                                           |
+    +--------------+                                          |
+    |    br-eth1   |                                   172.168.1.2/24
+    +--------------+                                  +---------------+
+    |    eth1      |----------------------------------|      eth1     |
+    +--------------+                                  +---------------+
+
+    Host A with OVS.                                      Remote host.
+
+With this setup, ping to VXLAN target device (``192.168.1.2``) should work.
+
+Tunneling-related Commands
+--------------------------
+
+Tunnel routing table
+~~~~~~~~~~~~~~~~~~~~
+
+To add route:
+
+::
+
+    $ ovs-appctl ovs/route/add <IP address>/<prefix length> <output-bridge-name> <gw>
+
+To see all routes configured:
+
+::
+
+    $ ovs-appctl ovs/route/show
+
+To delete route:
+
+::
+
+    $ ovs-appctl ovs/route/del <IP address>/<prefix length>
+
+To look up and display the route for a destination:
+
+::
+
+    $ ovs-appctl ovs/route/lookup <IP address>
+
+ARP
+~~~
+
+To see arp cache content:
+
+::
+
+    $ ovs-appctl tnl/arp/show
+
+To flush arp cache:
+
+::
+
+    $ ovs-appctl tnl/arp/flush
+
+Ports
+~~~~~
+
+To check tunnel ports listening in ovs-vswitchd:
+
+::
+
+    $ ovs-appctl tnl/ports/show
+
+To set range for VxLan UDP source port:
+
+::
+
+    $ ovs-appctl tnl/egress_port_range <num1> <num2>
+
+To show current range:
+
+::
+
+    $ ovs-appctl tnl/egress_port_range
+
+Datapath
+~~~~~~~~
+
+To check datapath ports:
+
+::
+
+    $ ovs-appctl dpif/show
+
+To check datapath flows:
+
+::
+
+    $ ovs-appctl dpif/dump-flows

debian/openvswitch-common.docs

@@ -1,3 +1,3 @@
 FAQ.md
 INSTALL.DPDK.rst
-README-native-tunneling.md
+README-native-tunneling.rst

ofproto/ofproto-tnl-unixctl.man

@@ -1,6 +1,6 @@
 .SS "OPENVSWITCH TUNNELING COMMANDS"
 These commands query and modify OVS tunnel components. Ref to
-README-native-tunneling.md for more info.
+README-native-tunneling.rst for more info.
 .
 .IP "\fBovs/route/add ipv4_address/plen output_bridge [GW]\fR"
 Adds ipv4_address/plen route to vswitchd routing table. output_bridge

rhel/openvswitch.spec.in

@@ -248,7 +248,7 @@ exit 0
 /usr/share/openvswitch/vswitch.ovsschema
 /usr/share/openvswitch/vtep.ovsschema
 %doc COPYING DESIGN.md INSTALL.SSL.md NOTICE README.rst WHY-OVS.rst FAQ.md NEWS
-%doc INSTALL.DPDK.rst rhel/README.RHEL README-native-tunneling.md
+%doc INSTALL.DPDK.rst rhel/README.RHEL README-native-tunneling.rst
 /var/lib/openvswitch
 /var/log/openvswitch
 

utilities/ovs-sim.1.xml

@@ -158,7 +158,7 @@ ovs-vsctl add-br br0  # Add bridge br0 inside hv0.
           replaced by <code>dummy</code> devices.  Other types of devices,
           however, retain their usual functions, which means that, e.g.,
           <code>vxlan</code> tunnels still act as tunnels (see
-          <code>README-native-tunneling.md</code>).
+          <code>README-native-tunneling.rst</code>).
         </p>
       </dd>