1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
|
=======
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
=======
.. program: ovs-sim
*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``.
|
