path: root/utilities/ovs-sim.1.xml

<?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 (see
          <code>README-native-tunneling.md</code>).
        </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 lswitch-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 lport-add lsw0 lp$i
    ovn-nbctl lport-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 lswitch-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 lport-add br0 lp$i
    ovn-nbctl lport-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 lport-get-up lp$i` != up; then echo $i; fi; done'
    </pre>

</manpage>