ovs-sim provides a convenient environment for running one or more
Open vSwitch instances and related software in a sandboxed
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.gitcd ovs./configuremakeutilities/ovs-sim
When invoked in the most ordinary way as shown above, ovs-sim
does the following:
Creates a directory sandbox as a subdirectory of the
current directory (first destroying such a directory if
it already exists) and cds into that directory.
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.
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 mainas main
See Commands, below, for an explanation.
Runs any scripts specified on the command line (see
Options below). The scripts can use arbitrary Bash
syntax, plus the additional commands described under
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.
ovs-sim accepts the following options and arguments:
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
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.
Scripts and interactive usage may use the following commands
implemented by ovs-sim. They are implemented as Bash shell
functions exported to subshells.
These are the basic commands for working with sandboxed Open
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
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 create
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).
Sets sandbox as the default simulation target for
Open vSwitch commands (e.g. ovs-vsctl, ovs-ofctl,
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.
Creates a new interconnection network named
net_attach network bridge
Adds a new port to bridge in the default sandbox
(as set with as) and plugs it into the network
interconnection network. network must already have
been created by a previous invocation of net_add.
The default sandbox must not be main.
These commands interact with OVN, the Open Virtual Network.
Creates and initializes the central OVN databases
(both ovn-sb(5) and ovn-nb) 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.
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 n1for i in 0 1; dosim_add hv$ias hv$i ovs-vsctl add-br br0 -- add-port br0 vif$ias hv$i net_attach n1 br0done
Here’s an extended version that also starts OVN:
ovn_startovn-nbctl ls-add lsw0net_add n1for i in 0 1; dosim_add hv$ias hv$iovs-vsctl add-br br-physovn_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$iovn-nbctl lsp-add lsw0 lp$iovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$idone
Here’s a primitive OVN ``scale test’’ (adjust the scale by
changing n in the first line :
n=200; export novn_startnet_add n1ovn-nbctl ls-add br0for i in `seq $n`; do(sim_add hv$ias hv$iovs-vsctl add-br br-physy=$(expr $i / 256)x=$(expr $i % 256)ovn_attach n1 br-phys 192.168.$y.$xovs-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 ;;esacdonewaitfor i in `seq $n`; doyy=$(printf %02x $(expr $i / 256))xx=$(printf $02x $(expr $i % 256))ovn-nbctl lsp-add br0 lp$iovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xxdone
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’
This page is part of the Open vSwitch (a distributed virtual
multilayer switch) project. Information about the project can be
found at ⟨http://openvswitch.org/⟩. If you have a bug report for
this manual page, send it to firstname.lastname@example.org. This page was
obtained from the project's upstream Git repository
⟨https://github.com/openvswitch/ovs.git⟩ on 2021-08-27. (At that
time, the date of the most recent commit that was found in the
repository was 2021-08-20.) If you discover any rendering
problems in this HTML version of the page, or you believe there
is a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
Open vSwitch 2.8.90 ovs-sim ovs-sim(1)