summaryrefslogtreecommitdiff
path: root/utilities/ovs-sim.1.xml
blob: 36be81263d8e6844cdb80ca2020799ade9685878 (plain)
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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
<?xml version="1.0" encoding="utf-8"?>
<manpage program="ovs-sim" section="1" title="ovs-sim">
    <h1>Name</h1>
    <p>ovs-sim -- Open vSwitch simulator environment</p>

    <h1>Synopsis</h1>
    <p><code>ovs-sim</code> [<var>option</var>]... [<var>script</var>]...</p>

    <h1>Description</h1>
    <p>
      <code>ovs-sim</code> provides a convenient environment for running one or
      more Open vSwitch instances and related software in a sandboxed
      simulation environment.
    </p>

    <p>
      To use <code>ovs-sim</code>, first build Open vSwitch, then invoke it
      directly from the build directory, e.g.:
    </p>

    <pre>
git clone https://github.com/openvswitch/ovs.git
cd ovs
./configure
make
utilities/ovs-sim
    </pre>

    <p>
      When invoked in the most ordinary way as shown above,
      <code>ovs-sim</code> does the following:
    </p>

    <ol>
      <li>
        Creates a directory <code>sandbox</code> as a subdirectory of the
        current directory (first destroying such a directory if it already
        exists) and <code>cd</code>s into that directory.
      </li>

      <li>
        Installs all of the Open vSwitch manpages into a <code>man</code>
        subdirectory of <code>sandbox</code> and adjusts the <env>MANPATH</env>
        environment variable so that <code>man</code> and other manpage viewers
        can find them.
      </li>

      <li>
        <p>
          Creates a simulated Open vSwitch named <code>main</code> and sets it
          up as the default target for OVS commands, as if the following
          <code>ovs-sim</code> commands had been run:
        </p>

        <pre>
          sim_add main
          as main
        </pre>

        <p>
          See <code>Commands</code>, below, for an explanation.
        </p>
      </li>

      <li>
        Runs any scripts specified on the command line (see
        <code>Options</code> below).  The scripts can use arbitrary Bash
        syntax, plus the additional commands described under
        <code>Commands</code>, below.
      </li>

      <li>
        If no scripts were specified, or if <option>-i</option> or
        <option>--interactive</option> was specified, invokes an interactive
        Bash subshell.  The user can use arbitrary Bash commands, plus the
        additional commands described under <code>Commands</code>, below.
      </li>
    </ol>

    <p>
      <code>ovs-sim</code> and the sandbox environment that it creates does not
      require superuser or other special privileges.  Generally, it should not
      be run with such privileges.
    </p>

    <h1>Options</h1>

    <p>
      <code>ovs-sim</code> accepts the following options and arguments:
    </p>

    <dl>
      <dt><var>script</var></dt>
      <dd>
        Runs <var>script</var>, which should be a Bash script, within a
        subshell after initializing.  If multiple <var>script</var> arguments
        are given, then they are run in the order given.  If any
        <var>script</var> exits with a nonzero exit code, then
        <code>ovs-sim</code> exits immediately with the same exit code.
      </dd>

      <dt><option>-i</option></dt>
      <dt><option>--interactive</option></dt>
      <dd>
        By default, if any <var>script</var> is specified, <code>ovs-sim</code>
        exits as soon as the scripts finish executing.  With this option, or if
        no scripts are specified, <code>ovs-sim</code> instead starts an
        interactive Bash session.
      </dd>
    </dl>

    <h1>Commands</h1>

    <p>
      Scripts and interactive usage may use the following commands implemented
      by <code>ovs-sim</code>.  They are implemented as Bash shell functions
      exported to subshells.
    </p>

    <h2>Basic Commands</h2>

    <p>
      These are the basic commands for working with sandboxed Open vSwitch
      instances.
    </p>

    <dl>
      <dt><code>sim_add</code> <var>sandbox</var></dt>
      <dd>
        <p>
          Starts a new simulated Open vSwitch instance named
          <var>sandbox</var>.  Files related to the instance, such as logs,
          databases, sockets, and pidfiles, are created in a subdirectory also
          named <var>sandbox</var>.  Afterward, the <code>as</code> command
          (see below) can be used to run Open vSwitch utilities in the context
          of the new sandbox.
        </p>

        <p>
          The new sandbox starts out without any bridges.  Use
          <code>ovs-vsctl</code> in the context of the new sandbox to create a
          bridge, e.g.:
        </p>

        <pre>
sim_add hv0           # Create sandbox hv0.  
as hv0                # Set hv0 as default sandbox.
ovs-vsctl add-br br0  # Add bridge br0 inside hv0.
        </pre>

        <p>
          The Open vSwitch instances that <code>sim_add</code> create enable
          ``dummy'' devices.  This means that bridges and interfaces can be
          created with type <code>dummy</code> to indicate that they should be
          totally simulated, without any reference to system entities.  In
          fact, <code>ovs-sim</code> also configures Open vSwitch so that the
          default <code>system</code> type of bridges and interfaces are
          replaced by <code>dummy</code> devices.  Other types of devices,
          however, retain their usual functions, which means that, e.g.,
          <code>vxlan</code> tunnels still act as tunnels (see
          <code>README-native-tunneling.md</code>).
        </p>
      </dd>

      <dt><code>as</code> <var>sandbox</var></dt>
      <dd>
        <p>
          Sets <var>sandbox</var> as the default simulation target for Open
          vSwitch commands (e.g. <code>ovs-vsctl</code>,
          <code>ovs-ofctl</code>, <code>ovs-appctl</code>).
        </p>

        <p>
          This command updates the beginning of the shell prompt to indicate
          the new default target.
        </p>
      </dd>

      <dt><code>as</code> <var>sandbox</var> <var>command</var> <var>arg</var>...</dt>
      <dd>
        Runs the given <var>command</var> with <var>sandbox</var> as the
        simulation target, e.g. <code>as hv0 ovs-vsctl add-br br0</code> runs
        <code>ovs-vsctl add-br br0</code> within sandbox <code>hv0</code>.
        The default target is unchanged.
      </dd>
    </dl>

    <h2>Interconnection Network Commands</h2>

    <p>
      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
      <code>ovs-sim</code> makes it easy to plug into other switches in other
      sandboxed Open vSwitch instances.  Interconnection networks are
      implemented as bridges in the <code>main</code> switch that
      <code>ovs-sim</code> creates by default, so to use interconnection
      networks please avoid working with <code>main</code> directly.
    </p>

    <dl>
      <dt><code>net_add</code> <var>network</var></dt>
      <dd>
        Creates a new interconnection network named <var>network</var>.
      </dd>

      <dt><code>net_attach</code> <var>network</var> <var>bridge</var></dt>
      <dd>
        Adds a new port to <var>bridge</var> in the default sandbox (as set
        with <code>as</code>) and plugs it into the <var>network</var>
        interconnection network.  <var>network</var> must already have been
        created by a previous invocation of <code>net_add</code>.  The default
        sandbox must not be <code>main</code>.
      </dd>
    </dl>

    <h2>OVN Commands</h2>

    <p>
      These commands interact with OVN, the Open Virtual Network.
    </p>

    <dl>
      <dt><code>ovn_start</code></dt>
      <dd>
        Creates and initializes the central OVN databases (both
        <code>ovn-sb</code>(5) and <code>ovn-nb</code>) and starts an instance
        of <code>ovsdb-server</code> for each one.  Also starts an instance of
        <code>ovn-northd</code>.
      </dd>

      <dt><code>ovn_attach</code> <var>network</var> <var>bridge</var> <var>ip</var> [<var>masklen</var>]</dt>
      <dd>
        First, this command attaches <var>bridge</var> to interconnection
        network <var>network</var>, just like <code>net_attach</code>
        <var>network</var> <var>bridge</var>.  Second, it configures
        (simulated) IP address <var>ip</var> (with network mask length
        <code>masklen</code>, which defaults to 24) on <var>bridge</var>.
        Finally, it configures the Open vSwitch database to work with OVN and
        starts <code>ovn-controller</code>.
      </dd>
    </dl>

    <h1>Examples</h1>

    <p>
      The following creates a pair of Open vSwitch instances
      <code>hv0</code> and <code>hv1</code>, adds a port named
      <code>vif0</code> or <code>vif1</code>, respectively, to each
      one, and then connects the two through an interconnection
      network <code>n1</code>:
    </p>

    <pre>
net_add n1
for i in 0 1; do
    sim_add hv$i
    as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i
    as hv$i net_attach n1 br0
done
    </pre>

    <p>
      Here's an extended version that also starts OVN:
    </p>

    <pre>
ovn_start
ovn-nbctl ls-add lsw0

net_add n1
for i in 0 1; do
    sim_add hv$i
    as hv$i
    ovs-vsctl add-br br-phys
    ovn_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$i
    ovn-nbctl lsp-add lsw0 lp$i
    ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$i
done
    </pre>
    
    <p>
      Here's a primitive OVN ``scale test'' (adjust the scale by
      changing <var>n</var> in the first line :
    </p>

    <pre>
n=200; export n
ovn_start
net_add n1
ovn-nbctl ls-add br0
for i in `seq $n`; do
    (sim_add hv$i
    as hv$i
    ovs-vsctl add-br br-phys
    y=$(expr $i / 256)
    x=$(expr $i % 256)
    ovn_attach n1 br-phys 192.168.$y.$x
    ovs-vsctl add-port br-int vif$i -- set Interface vif$i external-ids:iface-id=lp$i) &amp;
    case $i in
        *50|*00) echo $i; wait ;;
    esac
done
wait
for i in `seq $n`; do
    yy=$(printf %02x $(expr $i / 256))
    xx=$(printf $02x $(expr $i % 256))
    ovn-nbctl lsp-add br0 lp$i
    ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xx
done
    </pre>

    <p>
      When the scale test has finished initializing, you can watch the
      logical ports come up with a command like this:
    </p>

    <pre>
watch 'for i in `seq $n`; do if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done'
    </pre>

</manpage>