diff options
author | Ben Pfaff <blp@ovn.org> | 2018-05-17 12:31:45 -0700 |
---|---|---|
committer | Ben Pfaff <blp@ovn.org> | 2018-05-25 14:25:43 -0700 |
commit | ea38b8931a5bd59834c4f96a4fb68ffcc05fb6c3 (patch) | |
tree | b8675bfb059e98947e1a98c8539e50e97e2c5e46 /utilities | |
parent | 0f03ae3754ec8b30341befff81814fdc88cf0b88 (diff) | |
download | openvswitch-ea38b8931a5bd59834c4f96a4fb68ffcc05fb6c3.tar.gz |
ovs-sim: Convert documentation to RST format.
Signed-off-by: Ben Pfaff <blp@ovn.org>
Acked-by: Justin Pettit <jpettit@ovn.org>
Diffstat (limited to 'utilities')
-rw-r--r-- | utilities/.gitignore | 1 | ||||
-rw-r--r-- | utilities/automake.mk | 4 | ||||
-rw-r--r-- | utilities/ovs-sim.1.xml | 323 |
3 files changed, 1 insertions, 327 deletions
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) & - 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> |