diff mbox

[ovs-dev,10/15] doc: Convert README-native-tunneling to rST

Message ID 1476821025-4915-11-git-send-email-stephen@that.guru
State Accepted
Delegated to: Russell Bryant
Headers show

Commit Message

Stephen Finucane Oct. 18, 2016, 8:03 p.m. UTC 
Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 Makefile.am                     |   2 +-
 README-native-tunneling.md      |  85 -------------------
 README-native-tunneling.rst     | 176 ++++++++++++++++++++++++++++++++++++++++
 debian/openvswitch-common.docs  |   2 +-
 ofproto/ofproto-tnl-unixctl.man |   2 +-
 rhel/openvswitch.spec.in        |   2 +-
 utilities/ovs-sim.1.xml         |   2 +-
 7 files changed, 181 insertions(+), 90 deletions(-)
 delete mode 100644 README-native-tunneling.md
 create mode 100644 README-native-tunneling.rst

Comments

Russell Bryant Oct. 28, 2016, 9:25 p.m. UTC | #1 
On Tue, Oct 18, 2016 at 10:03 PM, Stephen Finucane <stephen@that.guru>
wrote:

> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  Makefile.am                     |   2 +-
>  README-native-tunneling.md      |  85 -------------------
>  README-native-tunneling.rst     | 176 ++++++++++++++++++++++++++++++
> ++++++++++
>  debian/openvswitch-common.docs  |   2 +-
>  ofproto/ofproto-tnl-unixctl.man |   2 +-
>  rhel/openvswitch.spec.in        |   2 +-
>  utilities/ovs-sim.1.xml         |   2 +-
>  7 files changed, 181 insertions(+), 90 deletions(-)
>  delete mode 100644 README-native-tunneling.md
>  create mode 100644 README-native-tunneling.rst
>

I've applied patches 9 and 10 to master.
Stephen Finucane Oct. 29, 2016, 11:50 a.m. UTC | #2 
On 28 Oct 23:25, Russell Bryant wrote:
> On Tue, Oct 18, 2016 at 10:03 PM, Stephen Finucane <stephen@that.guru>
> wrote:
> 
> > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > ---
> >  Makefile.am                     |   2 +-
> >  README-native-tunneling.md      |  85 -------------------
> >  README-native-tunneling.rst     | 176 ++++++++++++++++++++++++++++++
> > ++++++++++
> >  debian/openvswitch-common.docs  |   2 +-
> >  ofproto/ofproto-tnl-unixctl.man |   2 +-
> >  rhel/openvswitch.spec.in        |   2 +-
> >  utilities/ovs-sim.1.xml         |   2 +-
> >  7 files changed, 181 insertions(+), 90 deletions(-)
> >  delete mode 100644 README-native-tunneling.md
> >  create mode 100644 README-native-tunneling.rst
> >
> 
> I've applied patches 9 and 10 to master.

Excellent. You'll be delighted to hear I've the next batch lined up and
waiting :)

I do have a question though: there are READMEs in both the RHEL and
Debian packaging directories. I'm not sure should/can these be
converted to rST nor if they're something worth indexing for the docs.
Would you know what the custom is here?

Stephen
Russell Bryant Oct. 29, 2016, 4:26 p.m. UTC | #3 
On Sat, Oct 29, 2016 at 1:50 PM, Stephen Finucane <stephen@that.guru> wrote:

> On 28 Oct 23:25, Russell Bryant wrote:
> > On Tue, Oct 18, 2016 at 10:03 PM, Stephen Finucane <stephen@that.guru>
> > wrote:
> >
> > > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > > ---
> > >  Makefile.am                     |   2 +-
> > >  README-native-tunneling.md      |  85 -------------------
> > >  README-native-tunneling.rst     | 176 ++++++++++++++++++++++++++++++
> > > ++++++++++
> > >  debian/openvswitch-common.docs  |   2 +-
> > >  ofproto/ofproto-tnl-unixctl.man |   2 +-
> > >  rhel/openvswitch.spec.in        |   2 +-
> > >  utilities/ovs-sim.1.xml         |   2 +-
> > >  7 files changed, 181 insertions(+), 90 deletions(-)
> > >  delete mode 100644 README-native-tunneling.md
> > >  create mode 100644 README-native-tunneling.rst
> > >
> >
> > I've applied patches 9 and 10 to master.
>
> Excellent. You'll be delighted to hear I've the next batch lined up and
> waiting :)
>

Great.  I'm just trying to fit this in here and there.  I'll get through
them eventually.  :-)


> I do have a question though: there are READMEs in both the RHEL and
> Debian packaging directories. I'm not sure should/can these be
> converted to rST nor if they're something worth indexing for the docs.
> Would you know what the custom is here?
>

I'm not sure that I can indicate custom, but I can provide an opinion!

In general, I assume most documents are worth indexing.  I'm imagining that
we'll make a new index page once we get to sphinx.  Once we're there, we
can more clearly organize docs a bit by the audience.

README.RHEL definitely looks work publishing.  We should minimize sphinx
usage, as it's also installed as plain text by the OVS RPM.

I'm not sure which debian readme you're referring to from a quick look.
diff mbox

Patch

diff --git a/Makefile.am b/Makefile.am
index 42ad5d0..c1eba48 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -91,7 +91,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
diff --git a/README-native-tunneling.md b/README-native-tunneling.md
deleted file mode 100644
index 985deb3..0000000
--- a/README-native-tunneling.md
+++ /dev/null
@@ -1,85 +0,0 @@ 
-Native Tunneling in Open vSwitch userspace
-------------------------------------------
-
-Open vSwitch supports tunneling in userspace. Tunneling is implemented in
-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. Lets 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, So final topology looks like:
-
-                 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
-There are following commands that shows internal tables:
-
-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 del 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
-
-To check tunnel ports listening in vswitchd:
-     ovs-appctl tnl/ports/show
-
-To set range for VxLan udp source port:
-     To set:
-         ovs-appctl tnl/egress_port_range <num1> <num2>
-     Shows Current range:
-         ovs-appctl tnl/egress_port_range
-
-To check datapath ports:
-     ovs-appctl dpif/show
-
-To check datapath flows:
-     ovs-appctl dpif/dump-flows
-
-Contact
-=======
-bugs@openvswitch.org
diff --git a/README-native-tunneling.rst b/README-native-tunneling.rst
new file mode 100644
index 0000000..78eee5b
--- /dev/null
+++ b/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
diff --git a/debian/openvswitch-common.docs b/debian/openvswitch-common.docs
index 7c7335e..950e78c 100644
--- a/debian/openvswitch-common.docs
+++ b/debian/openvswitch-common.docs
@@ -1,3 +1,3 @@ 
 FAQ.md
 INSTALL.DPDK.rst
-README-native-tunneling.md
+README-native-tunneling.rst
diff --git a/ofproto/ofproto-tnl-unixctl.man b/ofproto/ofproto-tnl-unixctl.man
index fa14b87..7767197 100644
--- a/ofproto/ofproto-tnl-unixctl.man
+++ b/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
diff --git a/rhel/openvswitch.spec.in b/rhel/openvswitch.spec.in
index be6449b..d473e76 100644
--- a/rhel/openvswitch.spec.in
+++ b/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
 
diff --git a/utilities/ovs-sim.1.xml b/utilities/ovs-sim.1.xml
index 36be812..0430e73 100644
--- a/utilities/ovs-sim.1.xml
+++ b/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>