1 <?xml version=
"1.0" encoding=
"utf-8"?>
2 <manpage program=
"ovs-sim" section=
"1" title=
"ovs-sim">
4 <p>ovs-sim -- Open vSwitch simulator environment
</p>
7 <p><code>ovs-sim
</code> [
<var>option
</var>]... [
<var>script
</var>]...
</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.
17 To use
<code>ovs-sim
</code>, first build Open vSwitch, then invoke it
18 directly from the build directory, e.g.:
22 git clone https://github.com/openvswitch/ovs.git
30 When invoked in the most ordinary way as shown above,
31 <code>ovs-sim
</code> does the following:
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.
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
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:
61 See
<code>Commands
</code>, below, for an explanation.
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.
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.
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.
89 <code>ovs-sim
</code> accepts the following options and arguments:
93 <dt><var>script
</var></dt>
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.
102 <dt><option>-i
</option></dt>
103 <dt><option>--interactive
</option></dt>
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.
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.
120 <h2>Basic Commands
</h2>
123 These are the basic commands for working with sandboxed Open vSwitch
128 <dt><code>sim_add
</code> <var>sandbox
</var></dt>
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
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
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.
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>).
165 <dt><code>as
</code> <var>sandbox
</var></dt>
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>).
174 This command updates the beginning of the shell prompt to indicate
175 the new default target.
179 <dt><code>as
</code> <var>sandbox
</var> <var>command
</var> <var>arg
</var>...
</dt>
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.
188 <h2>Interconnection Network Commands
</h2>
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.
202 <dt><code>net_add
</code> <var>network
</var></dt>
204 Creates a new interconnection network named
<var>network
</var>.
207 <dt><code>net_attach
</code> <var>network
</var> <var>bridge
</var></dt>
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>.
217 <h2>OVN Commands
</h2>
220 These commands interact with OVN, the Open Virtual Network.
224 <dt><code>ovn_start
</code></dt>
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>.
232 <dt><code>ovn_attach
</code> <var>network
</var> <var>bridge
</var> <var>ip
</var> [
<var>masklen
</var>]
</dt>
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>.
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>:
258 as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i
259 as hv$i net_attach n1 br0
264 Here's an extended version that also starts OVN:
269 ovn-nbctl ls-add lsw0
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 lsp-add lsw0 lp$i
279 ovn-nbctl lsp-set-addresses lp$i f0:
00:
00:
00:
00:
0$i
284 Here's a primitive OVN ``scale test'' (adjust the scale by
285 changing
<var>n
</var> in the first line :
293 for i in `seq $n`; do
296 ovs-vsctl add-br br-phys
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)
&
302 *
50|*
00) echo $i; 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 lsp-add br0 lp$i
310 ovn-nbctl lsp-set-addresses lp$i f0:
00:
00:
00:$yy:$xx
315 When the scale test has finished initializing, you can watch the
316 logical ports come up with a command like this:
320 watch 'for i in `seq $n`; do if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done'