ovs-sim(1) — Linux manual page


OVS-SIM(1)                    Open vSwitch                    OVS-SIM(1)

NAME         top

       ovs-sim - Open vSwitch simulator environment

SYNOPSIS         top

       ovs-sim [option]… [script]…

DESCRIPTION         top

       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

       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         top

       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         top

       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

       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

   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.

AUTHOR         top

       The Open vSwitch Development Community

COPYRIGHT         top

       2016-2021, The Open vSwitch Development Community

COLOPHON         top

       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 bugs@openvswitch.org.  This page was
       obtained from the project's upstream Git repository
       ⟨https://github.com/openvswitch/ovs.git⟩ on 2023-12-22.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2023-12-21.)  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

3.2.90                        Dec 22, 2023                    OVS-SIM(1)