]>
Commit | Line | Data |
---|---|---|
6901639b BP |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <manpage program="ovs-sim" section="1" title="ovs-sim"> | |
3 | <h1>Name</h1> | |
4 | <p>ovs-sim -- Open vSwitch simulator environment</p> | |
5 | ||
6 | <h1>Synopsis</h1> | |
7 | <p><code>ovs-sim</code> [<var>option</var>]... [<var>script</var>]...</p> | |
8 | ||
9 | <h1>Description</h1> | |
10 | <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. | |
14 | </p> | |
15 | ||
16 | <p> | |
17 | To use <code>ovs-sim</code>, first build Open vSwitch, then invoke it | |
18 | directly from the build directory, e.g.: | |
19 | </p> | |
20 | ||
21 | <pre> | |
22 | git clone https://github.com/openvswitch/ovs.git | |
23 | cd ovs | |
24 | ./configure | |
25 | make | |
26 | utilities/ovs-sim | |
27 | </pre> | |
28 | ||
29 | <p> | |
30 | When invoked in the most ordinary way as shown above, | |
31 | <code>ovs-sim</code> does the following: | |
32 | </p> | |
33 | ||
34 | <ol> | |
35 | <li> | |
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. | |
39 | </li> | |
40 | ||
41 | <li> | |
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 | |
45 | can find them. | |
46 | </li> | |
47 | ||
48 | <li> | |
49 | <p> | |
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: | |
53 | </p> | |
54 | ||
55 | <pre> | |
56 | sim_add main | |
57 | as main | |
58 | </pre> | |
59 | ||
60 | <p> | |
61 | See <code>Commands</code>, below, for an explanation. | |
62 | </p> | |
63 | </li> | |
64 | ||
65 | <li> | |
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. | |
70 | </li> | |
71 | ||
72 | <li> | |
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. | |
77 | </li> | |
78 | </ol> | |
79 | ||
80 | <p> | |
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. | |
84 | </p> | |
85 | ||
86 | <h1>Options</h1> | |
87 | ||
88 | <p> | |
89 | <code>ovs-sim</code> accepts the following options and arguments: | |
90 | </p> | |
91 | ||
92 | <dl> | |
93 | <dt><var>script</var></dt> | |
94 | <dd> | |
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. | |
100 | </dd> | |
101 | ||
102 | <dt><option>-i</option></dt> | |
103 | <dt><option>--interactive</option></dt> | |
104 | <dd> | |
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. | |
109 | </dd> | |
110 | </dl> | |
111 | ||
112 | <h1>Commands</h1> | |
113 | ||
114 | <p> | |
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. | |
118 | </p> | |
119 | ||
120 | <h2>Basic Commands</h2> | |
121 | ||
122 | <p> | |
123 | These are the basic commands for working with sandboxed Open vSwitch | |
124 | instances. | |
125 | </p> | |
126 | ||
127 | <dl> | |
128 | <dt><code>sim_add</code> <var>sandbox</var></dt> | |
129 | <dd> | |
130 | <p> | |
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 | |
136 | of the new sandbox. | |
137 | </p> | |
138 | ||
139 | <p> | |
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 | |
142 | bridge, e.g.: | |
143 | </p> | |
144 | ||
145 | <pre> | |
43f317ff | 146 | sim_add hv0 # Create sandbox hv0. |
6901639b BP |
147 | as hv0 # Set hv0 as default sandbox. |
148 | ovs-vsctl add-br br0 # Add bridge br0 inside hv0. | |
149 | </pre> | |
150 | ||
151 | <p> | |
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., | |
43f317ff SF |
160 | <code>vxlan</code> tunnels still act as tunnels (refer to the |
161 | documentation). | |
6901639b BP |
162 | </p> |
163 | </dd> | |
164 | ||
165 | <dt><code>as</code> <var>sandbox</var></dt> | |
166 | <dd> | |
167 | <p> | |
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>). | |
171 | </p> | |
172 | ||
173 | <p> | |
174 | This command updates the beginning of the shell prompt to indicate | |
175 | the new default target. | |
176 | </p> | |
177 | </dd> | |
178 | ||
179 | <dt><code>as</code> <var>sandbox</var> <var>command</var> <var>arg</var>...</dt> | |
180 | <dd> | |
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. | |
185 | </dd> | |
186 | </dl> | |
187 | ||
188 | <h2>Interconnection Network Commands</h2> | |
189 | ||
190 | <p> | |
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. | |
199 | </p> | |
200 | ||
201 | <dl> | |
202 | <dt><code>net_add</code> <var>network</var></dt> | |
203 | <dd> | |
204 | Creates a new interconnection network named <var>network</var>. | |
205 | </dd> | |
206 | ||
207 | <dt><code>net_attach</code> <var>network</var> <var>bridge</var></dt> | |
208 | <dd> | |
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>. | |
214 | </dd> | |
215 | </dl> | |
216 | ||
217 | <h2>OVN Commands</h2> | |
218 | ||
219 | <p> | |
220 | These commands interact with OVN, the Open Virtual Network. | |
221 | </p> | |
222 | ||
223 | <dl> | |
224 | <dt><code>ovn_start</code></dt> | |
225 | <dd> | |
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>. | |
230 | </dd> | |
231 | ||
232 | <dt><code>ovn_attach</code> <var>network</var> <var>bridge</var> <var>ip</var> [<var>masklen</var>]</dt> | |
233 | <dd> | |
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>. | |
241 | </dd> | |
242 | </dl> | |
243 | ||
244 | <h1>Examples</h1> | |
245 | ||
246 | <p> | |
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>: | |
252 | </p> | |
253 | ||
254 | <pre> | |
255 | net_add n1 | |
256 | for i in 0 1; do | |
257 | sim_add hv$i | |
258 | as hv$i ovs-vsctl add-br br0 -- add-port br0 vif$i | |
259 | as hv$i net_attach n1 br0 | |
260 | done | |
261 | </pre> | |
262 | ||
263 | <p> | |
264 | Here's an extended version that also starts OVN: | |
265 | </p> | |
266 | ||
267 | <pre> | |
268 | ovn_start | |
ea46a4e9 | 269 | ovn-nbctl ls-add lsw0 |
6901639b BP |
270 | |
271 | net_add n1 | |
272 | for i in 0 1; do | |
273 | sim_add hv$i | |
274 | as hv$i | |
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 | |
31ed1192 JP |
278 | ovn-nbctl lsp-add lsw0 lp$i |
279 | ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:00:0$i | |
6901639b BP |
280 | done |
281 | </pre> | |
282 | ||
283 | <p> | |
284 | Here's a primitive OVN ``scale test'' (adjust the scale by | |
285 | changing <var>n</var> in the first line : | |
286 | </p> | |
287 | ||
288 | <pre> | |
289 | n=200; export n | |
290 | ovn_start | |
291 | net_add n1 | |
ea46a4e9 | 292 | ovn-nbctl ls-add br0 |
6901639b BP |
293 | for i in `seq $n`; do |
294 | (sim_add hv$i | |
295 | as hv$i | |
296 | ovs-vsctl add-br br-phys | |
297 | y=$(expr $i / 256) | |
298 | x=$(expr $i % 256) | |
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) & | |
301 | case $i in | |
999f13b5 | 302 | *50|*00) echo $i; wait ;; |
6901639b BP |
303 | esac |
304 | done | |
305 | wait | |
306 | for i in `seq $n`; do | |
307 | yy=$(printf %02x $(expr $i / 256)) | |
308 | xx=$(printf $02x $(expr $i % 256)) | |
31ed1192 JP |
309 | ovn-nbctl lsp-add br0 lp$i |
310 | ovn-nbctl lsp-set-addresses lp$i f0:00:00:00:$yy:$xx | |
6901639b BP |
311 | done |
312 | </pre> | |
313 | ||
314 | <p> | |
315 | When the scale test has finished initializing, you can watch the | |
316 | logical ports come up with a command like this: | |
317 | </p> | |
318 | ||
319 | <pre> | |
31ed1192 | 320 | watch 'for i in `seq $n`; do if test `ovn-nbctl lsp-get-up lp$i` != up; then echo $i; fi; done' |
6901639b BP |
321 | </pre> |
322 | ||
323 | </manpage> |