1OVS-CTL(8) Open vSwitch OVS-CTL(8)
2
6 ovs-ctl - OVS startup helper script
7
9 ovs-ctl --system-id=random|<uuid> [<options>] start
10 ovs-ctl stop
12 ovs-ctl --system-id=random|<uuid> [<options>] restart
14 ovs-ctl status
16 ovs-ctl version
18 ovs-ctl [<options>] load-kmod
20 ovs-ctl --system-id=random|<uuid> [<options>] force-reload-kmod
22 ovs-ctl [--protocol=<protocol>] [--sport=<sport>] [--dport=<dport>] en‐
24 able-protocol
25 ovs-ctl delete-transient-ports
27 ovs-ctl help | -h | --help
29 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 Each ovs-ctl command is described separately below.
38 The start command
40 The start command starts Open vSwitch. It performs the following
41 tasks:
42 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 The start command skips the following steps if ovsdb-server is already
50 running:
51 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 3. Starts ovsdb-server, unless the --no-ovsdb-server command option is
57 given.
58 4. Initializes a few values inside the database.
60 5. If the --delete-bridges option was used, deletes all of the bridges
62 from the database.
63 6. If the --delete-transient-ports option was used, deletes all ports
65 that have other_config:transient set to true.
66 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 7. Starts ovs-vswitchd.
71 Options
73 Several command-line options influence the start command’s behavior.
74 Some form of the following option should ordinarily be specified:
75 • --system-id=<uuid> or --system-id=random
77 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 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 The following options should be specified if the defaults are not suit‐
90 able:
91 • --system-type=<type> or --system-version=<version>
93 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 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 The following options are also likely to be useful:
105 • --external-id="<name>=<value>"
107 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 • --delete-bridges
113 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 • --delete-transient-ports
122 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 • --ovs-user=user[:group]
129 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 The following options are less important:
137 • --no-monitor
139 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 • --daemon-cwd=<directory>
145 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 • --no-force-corefiles
154 By default, ovs-ctl enables core dumps for the OVS daemons. This op‐
156 tion disables that behavior.
157 • --no-mlockall
159 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 • --no-self-confinement
165 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 • 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 • 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 • 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 • --ovsdb-server-priority=<niceness> or --ovs-vswitchd-priority=<nice‐
185 ness>
186 Sets the nice(1) level used for each daemon. All of them default to
188 -10.
189 • --ovsdb-server-wrapper=<wrapper> or --ovs-vswitchd-wrapper=<wrapper>
191 Configures the specified daemon to run under <wrapper>, which is one
193 of the following:
194 • valgrind: Run the daemon under valgrind(1), if it is installed,
196 logging to <daemon>.valgrind.log.<pid> in the log directory.
197 • strace: Run the daemon under strace(1), if it is installed, logging
199 to <daemon>.strace.log.<pid> in the log directory.
200 • glibc: Enable GNU C library features designed to find memory er‐
202 rors.
203 By default, no wrapper is used.
205 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 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 • --db-file=<file>
218 Overrides the file name for the OVS database.
220 • --db-sock=<socket>
222 Overrides the file name for the Unix domain socket used to connect to
224 ovsdb-server.
225 • --db-schema=<schema>
227 Overrides the file name for the OVS database schema.
229 • --extra-dbs=<file>
231 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 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 This command does nothing and finishes successfully if the OVS daemons
244 aren’t running.
245 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 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 The version command
258 The version command runs ovsdb-server --version and ovs-vswitchd --ver‐
259 sion.
260 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 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 2. Saves the OpenFlow flows of each bridge.
270 3. Stops the Open vSwitch daemons, as if by a call to ovs-ctl stop.
272 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 5. Unloads the Open vSwitch kernel module (including the bridge compat‐
278 ibility module if it is loaded).
279 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 7. Restores the kernel configuration state that was saved in step 4.
285 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 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 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 By default the load-kmod command attempts to load the openvswitch ker‐
307 nel module.
308 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 More specifically:
316 • 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 • 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 • Otherwise, this command installs a rule that accepts traffic of the
326 specified protocol.
327 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 The following options control the protocol to be enabled:
333 • --protocol=<protocol>
335 The name of the IP protocol to be enabled, such as gre or tcp. The
337 default is gre.
338 • --sport=<sport> or --dport=<dport>
340 TCP or UDP source or destination port to match. These are optional
342 and allowed only with --protocol=tcp or --protocol=udp.
343 The delete-transient-ports command
345 Deletes all ports that have the other_config:transient value set to
346 true.
347 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 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 • --no-ovsdb-server
360 Specifies that the ovs-ctl commands start, stop, and restart should
362 not modify the running status of ovsdb-server.
363 • --no-ovs-vswitchd
365 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 • PATH
379 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 • OVS_LOGDIR, OVS_RUNDIR, OVS_DBDIR, OVS_SYSCONFDIR, OVS_PKGDATADIR,
385 OVS_BINDIR, OVS_SBINDIR
386 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 • ovs-lib
395 Shell function library used internally by ovs-ctl. It must be in‐
397 stalled in the same directory as ovs-ctl.
398 • <logdir>/<daemon>.log
400 Per-daemon logfiles.
402 • <rundir>/<daemon>.pid
404 Per-daemon pidfiles to track whether a daemon is running and with
406 what process ID.
407 • <pkgdatadir>/vswitch.ovsschema
409 The OVS database schema used to initialize the database (use
411 --db-schema to override this location).
412 • <dbdir>/conf.db
414 The OVS database (use --db-file to override this location).
416 • <rundir>/openvswitch/db.sock
418 The Unix domain socket used for local communication with ovsdb-server
420 (use --db-sock to override this location).
421 • <sysconfdir>/openvswitch/system-id.conf
423 The persistent system UUID created and read by --system-id=random.
425 • <sysconfdir>/openvswitch/system-type.conf and <sysconfdir>/open‐
427 vswitch/system-version.conf
428 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 2021, The Open vSwitch Development Community
4452.15 Feb 21, 2021 OVS-CTL(8)