ovs-sim: Convert documentation to RST format.

Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Justin Pettit <jpettit@ovn.org>

7 files changed, 230 insertions, 328 deletions

diff --git a/Documentation/automake.mk b/Documentation/automake.mk
index 683ca1442..2202df45b 100644
--- a/Documentation/automake.mk
+++ b/Documentation/automake.mk
@@ -158,7 +158,8 @@ RST_MANPAGES = \
 	ovs-vlan-test.8.rst \
 	ovsdb-server.7.rst \
 	ovsdb.5.rst \
-	ovsdb.7.rst
+	ovsdb.7.rst \
+	ovs-sim.1.rst
 
 # The GNU standards say that these variables should control
 # installation directories for manpages in each section.  Automake
diff --git a/Documentation/conf.py b/Documentation/conf.py
index babda21de..0a61dc3f3 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -114,6 +114,8 @@ html_static_path = ['_static']
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 _man_pages = [
+    ('ovs-sim.1',
+     u'Open vSwitch simulator environment'),
     ('ovs-test.8',
      u'Check Linux drivers for performance, vlan and L3 tunneling problems'),
     ('ovs-vlan-test.8',
diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst
index 3d511decb..29183af62 100644
--- a/Documentation/ref/index.rst
+++ b/Documentation/ref/index.rst
@@ -39,6 +39,7 @@ time:
 .. toctree::
    :maxdepth: 3
 
+   ovs-sim.1
    ovs-test.8
    ovs-vlan-test.8
    ovsdb-server.7
diff --git a/Documentation/ref/ovs-sim.1.rst b/Documentation/ref/ovs-sim.1.rst
new file mode 100644
index 000000000..12e7f63f7
--- /dev/null
+++ b/Documentation/ref/ovs-sim.1.rst
@@ -0,0 +1,224 @@
+=======
+ovs-sim
+=======
+
+Synopsis
+========
+
+``ovs-sim`` [*option*]... [*script*]...
+
+Description
+===========
+
+``ovs-sim`` provides a convenient environment for running one or more Open
+vSwitch instances and related software in a sandboxed simulation environment.
+
+To use ``ovs-sim``, first build Open vSwitch, then invoke it directly from the
+build directory, e.g.::
+
+    git clone https://github.com/openvswitch/ovs.git
+    cd ovs
+    ./configure
+    make
+    utilities/ovs-sim
+
+When invoked in the most ordinary way as shown above, ovs-sim does  the
+following:
+
+1. Creates a directory ``sandbox`` as a subdirectory of the current
+   directory (first destroying such a directory if it already exists)
+   and makes it the current directory.
+
+2. Installs all of the Open vSwitch manpages into a ``man``
+   subdirectory of sandbox and adjusts the ``MANPATH`` environment
+   variable so that ``man`` and other manpage viewers can find them.
+
+3. Creates a simulated Open vSwitch named ``main`` and sets it up as the
+   default target for OVS commands, as if the following ``ovs-sim``
+   commands had been run::
+
+            sim_add main
+            as main
+
+  See `Commands`_, below, for an explanation.
+
+4. Runs  any  scripts  specified on the command line (see `Options`_,
+   below). The scripts can use arbitrary Bash  syntax,  plus  the
+   additional commands described under `Commands`_, below.
+
+5. If no scripts were specified, or if ``-i`` or ``--interactive`` was
+   specified, invokes an interactive Bash subshell. The user can use
+   arbitrary Bash commands, plus the additional commands described under
+   `Commands`_, below.
+
+``ovs-sim`` and the sandbox environment that it creates does not require
+superuser or other special privileges.  Generally, it should not be run with
+such privileges.
+
+Options
+=======
+
+.. program: ovs-sim
+
+*script*
+    Runs *script*, which should be a Bash script, within a subshell
+    after initializing.  If multiple script arguments are given, then
+    they are run in the order given.  If any script exits with a
+    nonzero exit code, then ``ovs-sim`` exits immediately with the
+    same exit code.
+
+``-i`` or ``--interactive``
+    By default, if any script is specified, ``ovs-sim`` exits as soon as the
+    scripts finish executing. With this option, or if no scripts are specified,
+    ``ovs-sim`` instead starts an interactive Bash session.
+
+Commands
+========
+
+Scripts and interactive usage may use the following commands
+implemented by ``ovs-sim``.  They are implemented as Bash shell functions
+exported to subshells.
+
+Basic Commands
+--------------
+
+These  are  the  basic commands for working with sandboxed Open vSwitch
+instances.
+
+``sim_add`` *sandbox*
+    Starts a new simulated Open vSwitch instance named *sandbox*.
+    Files related to the instance, such as logs, databases, sockets,
+    and pidfiles, are created in a subdirectory also named
+    *sandbox*. Afterward, the ``as`` command (see below) can be used
+    to run Open vSwitch utilities in the context of the new sandbox.
+
+    The new sandbox starts out without any bridges. Use ``ovs-vsctl``
+    in the context of the new sandbox to create a bridge, e.g.::
+
+	sim_add hv0           # Create sandbox hv0.
+	as hv0                # Set hv0 as default sandbox.
+	ovs-vsctl add-br br0  # Add bridge br0 inside hv0.
+
+    The Open vSwitch instances that ``sim_add`` creates enable
+    ``dummy`` devices.  This means that bridges and interfaces can be
+    created with type ``dummy`` to indicate that they should be
+    totally simulated, without any reference to system entities.  In
+    fact, ``ovs-sim`` also configures Open vSwitch so that the default
+    system type of bridges and interfaces are replaced by dummy
+    devices.  Other types of devices, however, retain their usual
+    functions, which means that, e.g., vxlan tunnels still act as
+    tunnels (refer to the documentation).
+
+``as`` *sandbox*
+    Sets sandbox as the default simulation target for Open vSwitch
+    commands (e.g. ``ovs-vsctl``, ``ovs-ofctl``, ``ovs-appctl``).
+
+    This command updates the beginning of the shell prompt to indicate
+    the new default target.
+
+``as`` *sandbox* *command* *arg*...
+    Runs the given command with *sandbox* as the simulation target,
+    e.g.  ``as hv0 ovs-vsctl add-br br0`` runs ``ovs-vsctl add-br
+    br0`` within sandbox ``hv0``.  The default target is unchanged.
+
+Interconnection Network Commands
+--------------------------------
+
+When multiple sandboxed Open vSwitch instances exist, one will
+inevitably want to connect them together.  These commands allow for
+that.  Conceptually, an interconnection network is a switch that
+``ovs-sim`` makes it easy to plug into other switches in other
+sandboxed Open vSwitch instances.  Interconnection networks are
+implemented as bridges in the ``main`` switch that ``ovs-sim`` creates
+by default, so to use interconnection networks please avoid working
+with ``main`` directly.
+
+``net_add`` *network*
+    Creates a new interconnection network named *network*.
+
+``net_attach`` *network* *bridge*
+    Adds a new port to *bridge* in the default sandbox (as set with
+    ``as``) and plugs it into interconnection network *network*, which
+    must already have been created by a previous invocation of
+    ``net_add``. The default sandbox must not be ``main``.
+
+OVN Commands
+------------
+
+These commands interact with OVN, the Open Virtual Network.
+
+``ovn_start``
+    Creates and initializes the central OVN databases (both
+    ``ovn-sb(5)`` and ``ovn-nb(5)``) and starts an instance of
+    ``ovsdb-server`` for each one.  Also starts an instance of
+    ``ovn-northd``.
+
+``ovn_attach`` *network* *bridge* *ip* [*masklen*]
+    First, this command attaches bridge to interconnection network
+    network, just like ``net_attach`` *network* *bridge*.  Second, it
+    configures (simulated) IP address *ip* (with network mask length
+    *masklen*, which defaults to 24) on *bridge*. Finally, it
+    configures the Open vSwitch database to work with OVN and starts
+    ``ovn-controller``.
+
+Examples
+========
+
+The following creates a pair of Open vSwitch instances ``hv0`` and
+``hv1``, adds a port named ``vif0`` or ``vif1``, respectively, to each
+one, and then connects the two through an interconnection network
+``n1``::
+
+    net_add n1
+    for i in 0 1; do
+	sim_add hv$i
+	as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i
+	as hv$i net_attach n1 br0
+    done
+
+Here’s an extended version that also starts OVN::
+
+    ovn_start
+    ovn-nbctl ls-add lsw0
+    net_add n1
+    for i in 0 1; do
+	sim_add hv$i
+	as hv$i
+	ovs-vsctl add-br br-phys
+	ovn_attach n1 br-phys 192.168.0.`expr $i + 1`
+	ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i
+	ovn-nbctl lsp-add lsw0 lp$i
+	ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$i
+    done
+
+Here’s a primitive OVN "scale test" (adjust the scale by changing
+``n`` in the first line::
+
+    n=200; export n
+    ovn_start
+    net_add n1
+    ovn-nbctl ls-add br0
+    for i in `seq $n`; do
+	(sim_add hv$i
+	as hv$i
+	ovs-vsctl add-br br-phys
+	y=$(expr $i / 256)
+	x=$(expr $i % 256)
+	ovn_attach n1 br-phys 192.168.$y.$x
+	ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i) &
+	case $i in
+	    *50|*00) echo $i; wait ;;
+	esac
+    done
+    wait
+    for i in `seq $n`; do
+	yy=$(printf %02x $(expr $i / 256))
+	xx=$(printf $02x $(expr $i % 256))
+	ovn-nbctl lsp-add br0 lp$i
+	ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xx
+    done
+
+When the scale test has finished initializing, you can watch the
+logical ports come up with a command like this::
+
+    watch 'for i in `seq $n`; do if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done'
diff --git a/utilities/.gitignore b/utilities/.gitignore
index 34c58f20f..aca5f1a34 100644
--- a/utilities/.gitignore
+++ b/utilities/.gitignore
@@ -37,4 +37,3 @@
 /ovs-vsctl
 /ovs-vsctl.8
 /ovs-sim
-/ovs-sim.1
diff --git a/utilities/automake.mk b/utilities/automake.mk
index afdbdb9f4..eb4fd6faa 100644
--- a/utilities/automake.mk
+++ b/utilities/automake.mk
@@ -31,8 +31,7 @@ check_SCRIPTS += \
 	utilities/ovs-appctl-bashcomp.bash \
 	utilities/ovs-vsctl-bashcomp.bash
 
-EXTRA_DIST += utilities/ovs-sim.in utilities/ovs-sim.1.xml
-noinst_man_MANS += utilities/ovs-sim.1
+EXTRA_DIST += utilities/ovs-sim.in
 noinst_SCRIPTS += utilities/ovs-sim
 
 utilities/ovs-lib: $(top_builddir)/config.status
@@ -92,7 +91,6 @@ CLEANFILES += \
 	utilities/ovs-pki \
 	utilities/ovs-pki.8 \
 	utilities/ovs-sim \
-	utilities/ovs-sim.1 \
 	utilities/ovs-tcpdump \
 	utilities/ovs-tcpdump.8 \
 	utilities/ovs-tcpundump \
diff --git a/utilities/ovs-sim.1.xml b/utilities/ovs-sim.1.xml
deleted file mode 100644
index 62ac22bb3..000000000
--- a/utilities/ovs-sim.1.xml
+++ /dev/null
@@ -1,323 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<manpage program="ovs-sim" section="1" title="ovs-sim">
-    <h1>Name</h1>
-    <p>ovs-sim -- Open vSwitch simulator environment</p>
-
-    <h1>Synopsis</h1>
-    <p><code>ovs-sim</code> [<var>option</var>]... [<var>script</var>]...</p>
-
-    <h1>Description</h1>
-    <p>
-      <code>ovs-sim</code> provides a convenient environment for running one or
-      more Open vSwitch instances and related software in a sandboxed
-      simulation environment.
-    </p>
-
-    <p>
-      To use <code>ovs-sim</code>, first build Open vSwitch, then invoke it
-      directly from the build directory, e.g.:
-    </p>
-
-    <pre>
-git clone https://github.com/openvswitch/ovs.git
-cd ovs
-./configure
-make
-utilities/ovs-sim
-    </pre>
-
-    <p>
-      When invoked in the most ordinary way as shown above,
-      <code>ovs-sim</code> does the following:
-    </p>
-
-    <ol>
-      <li>
-        Creates a directory <code>sandbox</code> as a subdirectory of the
-        current directory (first destroying such a directory if it already
-        exists) and <code>cd</code>s into that directory.
-      </li>
-
-      <li>
-        Installs all of the Open vSwitch manpages into a <code>man</code>
-        subdirectory of <code>sandbox</code> and adjusts the <env>MANPATH</env>
-        environment variable so that <code>man</code> and other manpage viewers
-        can find them.
-      </li>
-
-      <li>
-        <p>
-          Creates a simulated Open vSwitch named <code>main</code> and sets it
-          up as the default target for OVS commands, as if the following
-          <code>ovs-sim</code> commands had been run:
-        </p>
-
-        <pre>
-          sim_add main
-          as main
-        </pre>
-
-        <p>
-          See <code>Commands</code>, below, for an explanation.
-        </p>
-      </li>
-
-      <li>
-        Runs any scripts specified on the command line (see
-        <code>Options</code> below).  The scripts can use arbitrary Bash
-        syntax, plus the additional commands described under
-        <code>Commands</code>, below.
-      </li>
-
-      <li>
-        If no scripts were specified, or if <option>-i</option> or
-        <option>--interactive</option> was specified, invokes an interactive
-        Bash subshell.  The user can use arbitrary Bash commands, plus the
-        additional commands described under <code>Commands</code>, below.
-      </li>
-    </ol>
-
-    <p>
-      <code>ovs-sim</code> and the sandbox environment that it creates does not
-      require superuser or other special privileges.  Generally, it should not
-      be run with such privileges.
-    </p>
-
-    <h1>Options</h1>
-
-    <p>
-      <code>ovs-sim</code> accepts the following options and arguments:
-    </p>
-
-    <dl>
-      <dt><var>script</var></dt>
-      <dd>
-        Runs <var>script</var>, which should be a Bash script, within a
-        subshell after initializing.  If multiple <var>script</var> arguments
-        are given, then they are run in the order given.  If any
-        <var>script</var> exits with a nonzero exit code, then
-        <code>ovs-sim</code> exits immediately with the same exit code.
-      </dd>
-
-      <dt><option>-i</option></dt>
-      <dt><option>--interactive</option></dt>
-      <dd>
-        By default, if any <var>script</var> is specified, <code>ovs-sim</code>
-        exits as soon as the scripts finish executing.  With this option, or if
-        no scripts are specified, <code>ovs-sim</code> instead starts an
-        interactive Bash session.
-      </dd>
-    </dl>
-
-    <h1>Commands</h1>
-
-    <p>
-      Scripts and interactive usage may use the following commands implemented
-      by <code>ovs-sim</code>.  They are implemented as Bash shell functions
-      exported to subshells.
-    </p>
-
-    <h2>Basic Commands</h2>
-
-    <p>
-      These are the basic commands for working with sandboxed Open vSwitch
-      instances.
-    </p>
-
-    <dl>
-      <dt><code>sim_add</code> <var>sandbox</var></dt>
-      <dd>
-        <p>
-          Starts a new simulated Open vSwitch instance named
-          <var>sandbox</var>.  Files related to the instance, such as logs,
-          databases, sockets, and pidfiles, are created in a subdirectory also
-          named <var>sandbox</var>.  Afterward, the <code>as</code> command
-          (see below) can be used to run Open vSwitch utilities in the context
-          of the new sandbox.
-        </p>
-
-        <p>
-          The new sandbox starts out without any bridges.  Use
-          <code>ovs-vsctl</code> in the context of the new sandbox to create a
-          bridge, e.g.:
-        </p>
-
-        <pre>
-sim_add hv0           # Create sandbox hv0.
-as hv0                # Set hv0 as default sandbox.
-ovs-vsctl add-br br0  # Add bridge br0 inside hv0.
-        </pre>
-
-        <p>
-          The Open vSwitch instances that <code>sim_add</code> create enable
-          ``dummy'' devices.  This means that bridges and interfaces can be
-          created with type <code>dummy</code> to indicate that they should be
-          totally simulated, without any reference to system entities.  In
-          fact, <code>ovs-sim</code> also configures Open vSwitch so that the
-          default <code>system</code> type of bridges and interfaces are
-          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 (refer to the
-          documentation).
-        </p>
-      </dd>
-
-      <dt><code>as</code> <var>sandbox</var></dt>
-      <dd>
-        <p>
-          Sets <var>sandbox</var> as the default simulation target for Open
-          vSwitch commands (e.g. <code>ovs-vsctl</code>,
-          <code>ovs-ofctl</code>, <code>ovs-appctl</code>).
-        </p>
-
-        <p>
-          This command updates the beginning of the shell prompt to indicate
-          the new default target.
-        </p>
-      </dd>
-
-      <dt><code>as</code> <var>sandbox</var> <var>command</var> <var>arg</var>...</dt>
-      <dd>
-        Runs the given <var>command</var> with <var>sandbox</var> as the
-        simulation target, e.g. <code>as hv0 ovs-vsctl add-br br0</code> runs
-        <code>ovs-vsctl add-br br0</code> within sandbox <code>hv0</code>.
-        The default target is unchanged.
-      </dd>
-    </dl>
-
-    <h2>Interconnection Network Commands</h2>
-
-    <p>
-      When multiple sandboxed Open vSwitch instances exist, one will inevitably
-      want to connect them together.  These commands allow for that.
-      Conceptually, an interconnection network is a switch that
-      <code>ovs-sim</code> makes it easy to plug into other switches in other
-      sandboxed Open vSwitch instances.  Interconnection networks are
-      implemented as bridges in the <code>main</code> switch that
-      <code>ovs-sim</code> creates by default, so to use interconnection
-      networks please avoid working with <code>main</code> directly.
-    </p>
-
-    <dl>
-      <dt><code>net_add</code> <var>network</var></dt>
-      <dd>
-        Creates a new interconnection network named <var>network</var>.
-      </dd>
-
-      <dt><code>net_attach</code> <var>network</var> <var>bridge</var></dt>
-      <dd>
-        Adds a new port to <var>bridge</var> in the default sandbox (as set
-        with <code>as</code>) and plugs it into the <var>network</var>
-        interconnection network.  <var>network</var> must already have been
-        created by a previous invocation of <code>net_add</code>.  The default
-        sandbox must not be <code>main</code>.
-      </dd>
-    </dl>
-
-    <h2>OVN Commands</h2>
-
-    <p>
-      These commands interact with OVN, the Open Virtual Network.
-    </p>
-
-    <dl>
-      <dt><code>ovn_start</code></dt>
-      <dd>
-        Creates and initializes the central OVN databases (both
-        <code>ovn-sb</code>(5) and <code>ovn-nb</code>) and starts an instance
-        of <code>ovsdb-server</code> for each one.  Also starts an instance of
-        <code>ovn-northd</code>.
-      </dd>
-
-      <dt><code>ovn_attach</code> <var>network</var> <var>bridge</var> <var>ip</var> [<var>masklen</var>]</dt>
-      <dd>
-        First, this command attaches <var>bridge</var> to interconnection
-        network <var>network</var>, just like <code>net_attach</code>
-        <var>network</var> <var>bridge</var>.  Second, it configures
-        (simulated) IP address <var>ip</var> (with network mask length
-        <code>masklen</code>, which defaults to 24) on <var>bridge</var>.
-        Finally, it configures the Open vSwitch database to work with OVN and
-        starts <code>ovn-controller</code>.
-      </dd>
-    </dl>
-
-    <h1>Examples</h1>
-
-    <p>
-      The following creates a pair of Open vSwitch instances
-      <code>hv0</code> and <code>hv1</code>, adds a port named
-      <code>vif0</code> or <code>vif1</code>, respectively, to each
-      one, and then connects the two through an interconnection
-      network <code>n1</code>:
-    </p>
-
-    <pre>
-net_add n1
-for i in 0 1; do
-    sim_add hv$i
-    as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i
-    as hv$i net_attach n1 br0
-done
-    </pre>
-
-    <p>
-      Here's an extended version that also starts OVN:
-    </p>
-
-    <pre>
-ovn_start
-ovn-nbctl ls-add lsw0
-
-net_add n1
-for i in 0 1; do
-    sim_add hv$i
-    as hv$i
-    ovs-vsctl add-br br-phys
-    ovn_attach n1 br-phys 192.168.0.`expr $i + 1`
-    ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i
-    ovn-nbctl lsp-add lsw0 lp$i
-    ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$i
-done
-    </pre>
-    
-    <p>
-      Here's a primitive OVN ``scale test'' (adjust the scale by
-      changing <var>n</var> in the first line :
-    </p>
-
-    <pre>
-n=200; export n
-ovn_start
-net_add n1
-ovn-nbctl ls-add br0
-for i in `seq $n`; do
-    (sim_add hv$i
-    as hv$i
-    ovs-vsctl add-br br-phys
-    y=$(expr $i / 256)
-    x=$(expr $i % 256)
-    ovn_attach n1 br-phys 192.168.$y.$x
-    ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i) &amp;
-    case $i in
-        *50|*00) echo $i; wait ;;
-    esac
-done
-wait
-for i in `seq $n`; do
-    yy=$(printf %02x $(expr $i / 256))
-    xx=$(printf $02x $(expr $i % 256))
-    ovn-nbctl lsp-add br0 lp$i
-    ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xx
-done
-    </pre>
-
-    <p>
-      When the scale test has finished initializing, you can watch the
-      logical ports come up with a command like this:
-    </p>
-
-    <pre>
-watch 'for i in `seq $n`; do if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done'
-    </pre>
-
-</manpage>