1OVS-CTL(8) Open vSwitch OVS-CTL(8)
2
3
4
6 ovs-ctl - OVS startup helper script
7
9 ovs-ctl --system-id=random|<uuid> [<options>] start
10
11 ovs-ctl stop
12
13 ovs-ctl --system-id=random|<uuid> [<options>] restart
14
15 ovs-ctl status
16
17 ovs-ctl version
18
19 ovs-ctl [<options>] load-kmod
20
21 ovs-ctl --system-id=random|<uuid> [<options>] force-reload-kmod
22
23 ovs-ctl [--protocol=<protocol>] [--sport=<sport>] [--dport=<dport>] en‐
24 able-protocol
25
26 ovs-ctl delete-transient-ports
27
28 ovs-ctl help | -h | --help
29
30 ovs-ctl --version
31
33 The ovs-ctl program starts, stops, and checks the status of Open
34 vSwitch daemons. It is not meant to be invoked directly by system ad‐
35 ministrators but to be called internally by system startup scripts.
36
37 Each ovs-ctl command is described separately below.
38
39 The start command
40 The start command starts Open vSwitch. It performs the following
41 tasks:
42
43 1. Loads the Open vSwitch kernel module. If this fails, and the Linux
44 bridge module is loaded but no bridges exist, it tries to unload the
45 bridge module and tries loading the Open vSwitch kernel module
46 again. (This is because the Open vSwitch kernel module cannot coex‐
47 ist with the Linux bridge module before 2.6.37.)
48
49 The start command skips the following steps if ovsdb-server is already
50 running:
51
52 2. If the Open vSwitch database file does not exist, it creates it. If
53 the database does exist, but it has an obsolete version, it upgrades
54 it to the latest schema.
55
56 3. Starts ovsdb-server, unless the --no-ovsdb-server command option is
57 given.
58
59 4. Initializes a few values inside the database.
60
61 5. If the --delete-bridges option was used, deletes all of the bridges
62 from the database.
63
64 6. If the --delete-transient-ports option was used, deletes all ports
65 that have other_config:transient set to true.
66
67 The start command skips the following step if ovs-vswitchd is already
68 running, or if the --no-ovs-vswitchd command option is given:
69
70 7. Starts ovs-vswitchd.
71
72 Options
73 Several command-line options influence the start command’s behavior.
74 Some form of the following option should ordinarily be specified:
75
76 • --system-id=<uuid> or --system-id=random
77
78 This specifies a unique system identifier to store into exter‐
79 nal-ids:system-id in the database’s Open_vSwitch table. Remote man‐
80 agers that talk to the Open vSwitch database server over network pro‐
81 tocols use this value to identify and distinguish Open vSwitch in‐
82 stances, so it should be unique (at least) within OVS instances that
83 will connect to a single controller.
84
85 When random is specified, ovs-ctl will generate a random ID that per‐
86 sists from one run to another (stored in a file). When another
87 string is specified ovs-ctl uses it literally.
88
89 The following options should be specified if the defaults are not suit‐
90 able:
91
92 • --system-type=<type> or --system-version=<version>
93
94 Sets the value to store in the system-type and system-version col‐
95 umns, respectively, in the database’s Open_vSwitch table. Remote
96 managers may use these values too determine the kind of system to
97 which they are connected (primarily for display to human administra‐
98 tors).
99
100 When not specified, ovs-ctl uses values from the optional sys‐
101 tem-type.conf and system-version.conf files (see Files) or it uses
102 the lsb_release program, if present, to provide reasonable defaults.
103
104 The following options are also likely to be useful:
105
106 • --external-id="<name>=<value>"
107
108 Sets external-ids:<name> to <value> in the database’s Open_vSwitch
109 table. Specifying this option multiple times adds multiple key-value
110 pairs.
111
112 • --delete-bridges
113
114 Ordinarily Open vSwitch bridges persist from one system boot to the
115 next, as long as the database is preserved. Some environments in‐
116 stead expect to re-create all of the bridges and other configuration
117 state on every boot. This option supports that, by deleting all Open
118 vSwitch bridges after starting ovsdb-server but before starting
119 ovs-vswitchd.
120
121 • --delete-transient-ports
122
123 Deletes all ports that have other_config:transient set to true. This
124 is important on certain environments where some ports are going to be
125 recreated after reboot, but other ports need to be persisted in the
126 database.
127
128 • --ovs-user=user[:group]
129
130 Ordinarily Open vSwitch daemons are started as the user invoking the
131 ovs-ctl command. Some system administrators would prefer to have the
132 various daemons spawn as different users in their environments. This
133 option allows passing the --user option to the ovsdb-server and
134 ovs-vswitchd daemons, allowing them to change their privilege levels.
135
136 The following options are less important:
137
138 • --no-monitor
139
140 By default ovs-ctl passes --monitor to ovs-vswitchd and ovsdb-server,
141 requesting that it spawn a process monitor which will restart the
142 daemon if it crashes. This option suppresses that behavior.
143
144 • --daemon-cwd=<directory>
145
146 Specifies the current working directory that the OVS daemons should
147 run from. The default is / (the root directory) if this option is
148 not specified. (This option is useful because most systems create
149 core files in a process’s current working directory and because a
150 file system that is in use as a process’s current working directory
151 cannot be unmounted.)
152
153 • --no-force-corefiles
154
155 By default, ovs-ctl enables core dumps for the OVS daemons. This op‐
156 tion disables that behavior.
157
158 • --no-mlockall
159
160 By default ovs-ctl passes --mlockall to ovs-vswitchd, requesting that
161 it lock all of its virtual memory, preventing it from being paged to
162 disk. This option suppresses that behavior.
163
164 • --no-self-confinement
165
166 Disable self-confinement for ovs-vswitchd and ovsdb-server daemons.
167 This flag may be used when, for example, OpenFlow controller creates
168 its Unix Domain Socket outside OVS run directory and OVS needs to
169 connect to it. It is better to stick with the default behavior and
170 not to use this flag, unless:
171
172 • You have Open vSwitch running under SELinux or AppArmor Mandatory
173 Access Control that would prevent OVS from messing with sockets
174 outside ordinary OVS directories.
175
176 • You believe that relying on protocol handshakes (e.g. OpenFlow) is
177 enough to prevent OVS to adversely interact with other daemons run‐
178 ning on your system.
179
180 • You don’t have much worries of remote OVSDB exploits in the first
181 place, because, perhaps, OVSDB manager is running on the same host
182 as OVS and share similar attack vectors.
183
184 • --ovsdb-server-priority=<niceness> or --ovs-vswitchd-priority=<nice‐
185 ness>
186
187 Sets the nice(1) level used for each daemon. All of them default to
188 -10.
189
190 • --ovsdb-server-wrapper=<wrapper> or --ovs-vswitchd-wrapper=<wrapper>
191
192 Configures the specified daemon to run under <wrapper>, which is one
193 of the following:
194
195 • valgrind: Run the daemon under valgrind(1), if it is installed,
196 logging to <daemon>.valgrind.log.<pid> in the log directory.
197
198 • strace: Run the daemon under strace(1), if it is installed, logging
199 to <daemon>.strace.log.<pid> in the log directory.
200
201 • glibc: Enable GNU C library features designed to find memory er‐
202 rors.
203
204 By default, no wrapper is used.
205
206 Each of the wrappers can expose bugs in Open vSwitch that lead to in‐
207 correct operation, including crashes. The valgrind and strace wrap‐
208 pers greatly slow daemon operations so they should not be used in
209 production. They also produce voluminous logs that can quickly fill
210 small disk partitions. The glibc wrapper is less resource-intensive
211 but still somewhat slows the daemons.
212
213 The following options control file locations. They should only be used
214 if the default locations cannot be used. See FILES, below, for more
215 information.
216
217 • --db-file=<file>
218
219 Overrides the file name for the OVS database.
220
221 • --db-sock=<socket>
222
223 Overrides the file name for the Unix domain socket used to connect to
224 ovsdb-server.
225
226 • --db-schema=<schema>
227
228 Overrides the file name for the OVS database schema.
229
230 • --extra-dbs=<file>
231
232 Adds <file> as an extra database for ovsdb-server to serve out. Mul‐
233 tiple space-separated file names may also be specified. <file>
234 should begin with /; if it does not, then it will be taken as rela‐
235 tive to <dbdir>.
236
237 The stop command
238 The stop command stops the ovs-vswitchd and ovsdb-server daemons. It
239 does not unload the Open vSwitch kernel modules. It can take the same
240 --no-ovsdb-server and --no-ovs-vswitchd options as that of the start
241 command.
242
243 This command does nothing and finishes successfully if the OVS daemons
244 aren’t running.
245
246 The restart command
247 The restart command performs a stop followed by a start command. The
248 command can take the same options as that of the start command. In ad‐
249 dition, it saves and restores OpenFlow flows for each individual
250 bridge.
251
252 The status command
253 The status command checks whether the OVS daemons ovs-vswitchd and
254 ovsdb-server are running and prints messages with that information. It
255 exits with status 0 if the daemons are running, 1 otherwise.
256
257 The version command
258 The version command runs ovsdb-server --version and ovs-vswitchd --ver‐
259 sion.
260
261 The force-reload-kmod command
262 The force-reload-kmod command allows upgrading the Open vSwitch kernel
263 module without rebooting. It performs the following tasks:
264
265 1. Gets a list of OVS “internal” interfaces, that is, network devices
266 implemented by Open vSwitch. The most common examples of these are
267 bridge “local ports”.
268
269 2. Saves the OpenFlow flows of each bridge.
270
271 3. Stops the Open vSwitch daemons, as if by a call to ovs-ctl stop.
272
273 4. Saves the kernel configuration state of the OVS internal interfaces
274 listed in step 1, including IP and IPv6 addresses and routing table
275 entries.
276
277 5. Unloads the Open vSwitch kernel module (including the bridge compat‐
278 ibility module if it is loaded).
279
280 6. Starts OVS back up, as if by a call to ovs-ctl start. This reloads
281 the kernel module, restarts the OVS daemons and finally restores the
282 saved OpenFlow flows.
283
284 7. Restores the kernel configuration state that was saved in step 4.
285
286 8. Checks for daemons that may need to be restarted because they have
287 packet sockets that are listening on old instances of Open vSwitch
288 kernel interfaces and, if it finds any, prints a warning on stdout.
289 DHCP is a common example: if the ISC DHCP client is running on an
290 OVS internal interface, then it will have to be restarted after com‐
291 pleting the above procedure. (It would be nice if ovs-ctl could
292 restart daemons automatically, but the details are far too specific
293 to a particular distribution and installation.)
294
295 force-kmod-reload internally stops and starts OVS, so it accepts all of
296 the options accepted by the start command except for the
297 --no-ovs-vswitchd option.
298
299 The load-kmod command
300 The load-kmod command loads the openvswitch kernel modules if they are
301 not already loaded. This operation also occurs as part of the start
302 command. The motivation for providing the load-kmod command is to al‐
303 low errors when loading modules to be handled separately from other er‐
304 rors that may occur when running the start command.
305
306 By default the load-kmod command attempts to load the openvswitch ker‐
307 nel module.
308
309 The enable-protocol command
310 The enable-protocol command checks for rules related to a specified
311 protocol in the system’s iptables(8) configuration. If there are no
312 rules specifically related to that protocol, then it inserts a rule to
313 accept the specified protocol.
314
315 More specifically:
316
317 • If iptables is not installed or not enabled, this command does noth‐
318 ing, assuming that lack of filtering means that the protocol is en‐
319 abled.
320
321 • If the INPUT chain has a rule that matches the specified protocol,
322 then this command does nothing, assuming that whatever rule is in‐
323 stalled reflects the system administrator’s decisions.
324
325 • Otherwise, this command installs a rule that accepts traffic of the
326 specified protocol.
327
328 This command normally completes successfully, even if it does nothing.
329 Only the failure of an attempt to insert a rule normally causes it to
330 return an exit code other than 0.
331
332 The following options control the protocol to be enabled:
333
334 • --protocol=<protocol>
335
336 The name of the IP protocol to be enabled, such as gre or tcp. The
337 default is gre.
338
339 • --sport=<sport> or --dport=<dport>
340
341 TCP or UDP source or destination port to match. These are optional
342 and allowed only with --protocol=tcp or --protocol=udp.
343
344 The delete-transient-ports command
345 Deletes all ports that have the other_config:transient value set to
346 true.
347
348 The help command
349 Prints a usage message and exits successfully.
350
352 In addition to the options listed for each command above, these options
353 control the behavior of several ovs-ctl commands.
354
355 By default, ovs-ctl controls the ovsdb-server and ovs-vswitchd daemons.
356 The following options restrict that control to exclude one or the
357 other:
358
359 • --no-ovsdb-server
360
361 Specifies that the ovs-ctl commands start, stop, and restart should
362 not modify the running status of ovsdb-server.
363
364 • --no-ovs-vswitchd
365
366 Specifies that the ovs-ctl commands start, stop, and restart should
367 not modify the running status of ovs-vswitchd. It is an error to in‐
368 clude this option with the force-reload-kmod command.
369
371 ovs-ctl exits with status 0 on success and nonzero on failure. The
372 start command is considered to succeed if OVS is already started; the
373 stop command is considered to succeed if OVS is already stopped.
374
376 The following environment variables affect ovs-ctl:
377
378 • PATH
379
380 ovs-ctl does not hardcode the location of any of the programs that it
381 runs. ovs-ctl will add the <sbindir> and <bindir> that were speci‐
382 fied at configure time to PATH, if they are not already present.
383
384 • OVS_LOGDIR, OVS_RUNDIR, OVS_DBDIR, OVS_SYSCONFDIR, OVS_PKGDATADIR,
385 OVS_BINDIR, OVS_SBINDIR
386
387 Setting one of these variables in the environment overrides the re‐
388 spective configure option, both for ovs-ctl itself and for the other
389 Open vSwitch programs that it runs.
390
392 ovs-ctl uses the following files:
393
394 • ovs-lib
395
396 Shell function library used internally by ovs-ctl. It must be in‐
397 stalled in the same directory as ovs-ctl.
398
399 • <logdir>/<daemon>.log
400
401 Per-daemon logfiles.
402
403 • <rundir>/<daemon>.pid
404
405 Per-daemon pidfiles to track whether a daemon is running and with
406 what process ID.
407
408 • <pkgdatadir>/vswitch.ovsschema
409
410 The OVS database schema used to initialize the database (use
411 --db-schema to override this location).
412
413 • <dbdir>/conf.db
414
415 The OVS database (use --db-file to override this location).
416
417 • <rundir>/openvswitch/db.sock
418
419 The Unix domain socket used for local communication with ovsdb-server
420 (use --db-sock to override this location).
421
422 • <sysconfdir>/openvswitch/system-id.conf
423
424 The persistent system UUID created and read by --system-id=random.
425
426 • <sysconfdir>/openvswitch/system-type.conf and <sysconfdir>/open‐
427 vswitch/system-version.conf
428
429 The system-type and system-version values stored in the database’s
430 Open_vSwitch table when not specified as a command-line option.
431
433 The files debian/openvswitch-switch.init and xenserver/etc_init.d_open‐
434 vswitch in the Open vSwitch source distribution are good examples of
435 how to use ovs-ctl.
436
438 README.rst, ovsdb-server(8), ovs-vswitchd(8).
439
441 The Open vSwitch Development Community
442
444 2016-2022, The Open vSwitch Development Community
445
446
447
448
4492.17 Jul 22, 2022 OVS-CTL(8)