utilities/ovs-sim.1.xml

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <manpage program="ovs-sim" section="1" title="ovs-sim">
   3     <h1>Name</h1>
   4     <p>ovs-sim -- Open vSwitch simulator environment</p>
   5
   6     <h1>Synopsis</h1>
   7     <p><code>ovs-sim</code> [<var>option</var>]... [<var>script</var>]...</p>
   8
   9     <h1>Description</h1>
  10     <p>
  11       <code>ovs-sim</code> provides a convenient environment for running one or
  12       more Open vSwitch instances and related software in a sandboxed
  13       simulation environment.
  14     </p>
  15
  16     <p>
  17       To use <code>ovs-sim</code>, first build Open vSwitch, then invoke it
  18       directly from the build directory, e.g.:
  19     </p>
  20
  21     <pre>
  22 git clone https://github.com/openvswitch/ovs.git
  23 cd ovs
  24 ./configure
  25 make
  26 utilities/ovs-sim
  27     </pre>
  28
  29     <p>
  30       When invoked in the most ordinary way as shown above,
  31       <code>ovs-sim</code> does the following:
  32     </p>
  33
  34     <ol>
  35       <li>
  36         Creates a directory <code>sandbox</code> as a subdirectory of the
  37         current directory (first destroying such a directory if it already
  38         exists) and <code>cd</code>s into that directory.
  39       </li>
  40
  41       <li>
  42         Installs all of the Open vSwitch manpages into a <code>man</code>
  43         subdirectory of <code>sandbox</code> and adjusts the <env>MANPATH</env>
  44         environment variable so that <code>man</code> and other manpage viewers
  45         can find them.
  46       </li>
  47
  48       <li>
  49         <p>
  50           Creates a simulated Open vSwitch named <code>main</code> and sets it
  51           up as the default target for OVS commands, as if the following
  52           <code>ovs-sim</code> commands had been run:
  53         </p>
  54
  55         <pre>
  56           sim_add main
  57           as main
  58         </pre>
  59
  60         <p>
  61           See <code>Commands</code>, below, for an explanation.
  62         </p>
  63       </li>
  64
  65       <li>
  66         Runs any scripts specified on the command line (see
  67         <code>Options</code> below).  The scripts can use arbitrary Bash
  68         syntax, plus the additional commands described under
  69         <code>Commands</code>, below.
  70       </li>
  71
  72       <li>
  73         If no scripts were specified, or if <option>-i</option> or
  74         <option>--interactive</option> was specified, invokes an interactive
  75         Bash subshell.  The user can use arbitrary Bash commands, plus the
  76         additional commands described under <code>Commands</code>, below.
  77       </li>
  78     </ol>
  79
  80     <p>
  81       <code>ovs-sim</code> and the sandbox environment that it creates does not
  82       require superuser or other special privileges.  Generally, it should not
  83       be run with such privileges.
  84     </p>
  85
  86     <h1>Options</h1>
  87
  88     <p>
  89       <code>ovs-sim</code> accepts the following options and arguments:
  90     </p>
  91
  92     <dl>
  93       <dt><var>script</var></dt>
  94       <dd>
  95         Runs <var>script</var>, which should be a Bash script, within a
  96         subshell after initializing.  If multiple <var>script</var> arguments
  97         are given, then they are run in the order given.  If any
  98         <var>script</var> exits with a nonzero exit code, then
  99         <code>ovs-sim</code> exits immediately with the same exit code.
 100       </dd>
 101
 102       <dt><option>-i</option></dt>
 103       <dt><option>--interactive</option></dt>
 104       <dd>
 105         By default, if any <var>script</var> is specified, <code>ovs-sim</code>
 106         exits as soon as the scripts finish executing.  With this option, or if
 107         no scripts are specified, <code>ovs-sim</code> instead starts an
 108         interactive Bash session.
 109       </dd>
 110     </dl>
 111
 112     <h1>Commands</h1>
 113
 114     <p>
 115       Scripts and interactive usage may use the following commands implemented
 116       by <code>ovs-sim</code>.  They are implemented as Bash shell functions
 117       exported to subshells.
 118     </p>
 119
 120     <h2>Basic Commands</h2>
 121
 122     <p>
 123       These are the basic commands for working with sandboxed Open vSwitch
 124       instances.
 125     </p>
 126
 127     <dl>
 128       <dt><code>sim_add</code> <var>sandbox</var></dt>
 129       <dd>
 130         <p>
 131           Starts a new simulated Open vSwitch instance named
 132           <var>sandbox</var>.  Files related to the instance, such as logs,
 133           databases, sockets, and pidfiles, are created in a subdirectory also
 134           named <var>sandbox</var>.  Afterward, the <code>as</code> command
 135           (see below) can be used to run Open vSwitch utilities in the context
 136           of the new sandbox.
 137         </p>
 138
 139         <p>
 140           The new sandbox starts out without any bridges.  Use
 141           <code>ovs-vsctl</code> in the context of the new sandbox to create a
 142           bridge, e.g.:
 143         </p>
 144
 145         <pre>
 146 sim_add hv0           # Create sandbox hv0.
 147 as hv0                # Set hv0 as default sandbox.
 148 ovs-vsctl add-br br0  # Add bridge br0 inside hv0.
 149         </pre>
 150
 151         <p>
 152           The Open vSwitch instances that <code>sim_add</code> create enable
 153           ``dummy'' devices.  This means that bridges and interfaces can be
 154           created with type <code>dummy</code> to indicate that they should be
 155           totally simulated, without any reference to system entities.  In
 156           fact, <code>ovs-sim</code> also configures Open vSwitch so that the
 157           default <code>system</code> type of bridges and interfaces are
 158           replaced by <code>dummy</code> devices.  Other types of devices,
 159           however, retain their usual functions, which means that, e.g.,
 160           <code>vxlan</code> tunnels still act as tunnels (see
 161           <code>README-native-tunneling.md</code>).
 162         </p>
 163       </dd>
 164
 165       <dt><code>as</code> <var>sandbox</var></dt>
 166       <dd>
 167         <p>
 168           Sets <var>sandbox</var> as the default simulation target for Open
 169           vSwitch commands (e.g. <code>ovs-vsctl</code>,
 170           <code>ovs-ofctl</code>, <code>ovs-appctl</code>).
 171         </p>
 172
 173         <p>
 174           This command updates the beginning of the shell prompt to indicate
 175           the new default target.
 176         </p>
 177       </dd>
 178
 179       <dt><code>as</code> <var>sandbox</var> <var>command</var> <var>arg</var>...</dt>
 180       <dd>
 181         Runs the given <var>command</var> with <var>sandbox</var> as the
 182         simulation target, e.g. <code>as hv0 ovs-vsctl add-br br0</code> runs
 183         <code>ovs-vsctl add-br br0</code> within sandbox <code>hv0</code>.
 184         The default target is unchanged.
 185       </dd>
 186     </dl>
 187
 188     <h2>Interconnection Network Commands</h2>
 189
 190     <p>
 191       When multiple sandboxed Open vSwitch instances exist, one will inevitably
 192       want to connect them together.  These commands allow for that.
 193       Conceptually, an interconnection network is a switch that
 194       <code>ovs-sim</code> makes it easy to plug into other switches in other
 195       sandboxed Open vSwitch instances.  Interconnection networks are
 196       implemented as bridges in the <code>main</code> switch that
 197       <code>ovs-sim</code> creates by default, so to use interconnection
 198       networks please avoid working with <code>main</code> directly.
 199     </p>
 200
 201     <dl>
 202       <dt><code>net_add</code> <var>network</var></dt>
 203       <dd>
 204         Creates a new interconnection network named <var>network</var>.
 205       </dd>
 206
 207       <dt><code>net_attach</code> <var>network</var> <var>bridge</var></dt>
 208       <dd>
 209         Adds a new port to <var>bridge</var> in the default sandbox (as set
 210         with <code>as</code>) and plugs it into the <var>network</var>
 211         interconnection network.  <var>network</var> must already have been
 212         created by a previous invocation of <code>net_add</code>.  The default
 213         sandbox must not be <code>main</code>.
 214       </dd>
 215     </dl>
 216
 217     <h2>OVN Commands</h2>
 218
 219     <p>
 220       These commands interact with OVN, the Open Virtual Network.
 221     </p>
 222
 223     <dl>
 224       <dt><code>ovn_start</code></dt>
 225       <dd>
 226         Creates and initializes the central OVN databases (both
 227         <code>ovn-sb</code>(5) and <code>ovn-nb</code>) and starts an instance
 228         of <code>ovsdb-server</code> for each one.  Also starts an instance of
 229         <code>ovn-northd</code>.
 230       </dd>
 231
 232       <dt><code>ovn_attach</code> <var>network</var> <var>bridge</var> <var>ip</var> [<var>masklen</var>]</dt>
 233       <dd>
 234         First, this command attaches <var>bridge</var> to interconnection
 235         network <var>network</var>, just like <code>net_attach</code>
 236         <var>network</var> <var>bridge</var>.  Second, it configures
 237         (simulated) IP address <var>ip</var> (with network mask length
 238         <code>masklen</code>, which defaults to 24) on <var>bridge</var>.
 239         Finally, it configures the Open vSwitch database to work with OVN and
 240         starts <code>ovn-controller</code>.
 241       </dd>
 242     </dl>
 243
 244     <h1>Examples</h1>
 245
 246     <p>
 247       The following creates a pair of Open vSwitch instances
 248       <code>hv0</code> and <code>hv1</code>, adds a port named
 249       <code>vif0</code> or <code>vif1</code>, respectively, to each
 250       one, and then connects the two through an interconnection
 251       network <code>n1</code>:
 252     </p>
 253
 254     <pre>
 255 net_add n1
 256 for i in 0 1; do
 257     sim_add hv$i
 258     as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i
 259     as hv$i net_attach n1 br0
 260 done
 261     </pre>
 262
 263     <p>
 264       Here's an extended version that also starts OVN:
 265     </p>
 266
 267     <pre>
 268 ovn_start
 269 ovn-nbctl lswitch-add lsw0
 270
 271 net_add n1
 272 for i in 0 1; do
 273     sim_add hv$i
 274     as hv$i
 275     ovs-vsctl add-br br-phys
 276     ovn_attach n1 br-phys 192.168.0.`expr $i + 1`
 277     ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i
 278     ovn-nbctl lport-add lsw0 lp$i
 279     ovn-nbctl lport-set-addresses lp$i f0:00:00:00:00:0$i
 280 done
 281     </pre>
 282
 283     <p>
 284       Here's a primitive OVN ``scale test'' (adjust the scale by
 285       changing <var>n</var> in the first line :
 286     </p>
 287
 288     <pre>
 289 n=200; export n
 290 ovn_start
 291 net_add n1
 292 ovn-nbctl lswitch-add br0
 293 for i in `seq $n`; do
 294     (sim_add hv$i
 295     as hv$i
 296     ovs-vsctl add-br br-phys
 297     y=$(expr $i / 256)
 298     x=$(expr $i % 256)
 299     ovn_attach n1 br-phys 192.168.$y.$x
 300     ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i) &amp;
 301     case $i in
 302         *50|*00) echo $i; wait ;;
 303     esac
 304 done
 305 wait
 306 for i in `seq $n`; do
 307     yy=$(printf %02x $(expr $i / 256))
 308     xx=$(printf $02x $(expr $i % 256))
 309     ovn-nbctl lport-add br0 lp$i
 310     ovn-nbctl lport-set-addresses lp$i f0:00:00:00:$yy:$xx
 311 done
 312     </pre>
 313
 314     <p>
 315       When the scale test has finished initializing, you can watch the
 316       logical ports come up with a command like this:
 317     </p>
 318
 319     <pre>
 320 watch 'for i in `seq $n`; do if test `ovn-nbctl lport-get-up lp$i` != up; then echo $i; fi; done'
 321     </pre>
 322
 323 </manpage>