# ovs-sim

## Synopsis

`ovs-sim` [option]… [script]…

## Description

`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
    ./configure
    make
    utilities/ovs-sim

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

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

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 documentation).

`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 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.

`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`.