1ovs-ctl(8) Open vSwitch Manual 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
11 ovs-ctl status
12 ovs-ctl version
13 ovs-ctl [options] load-kmod
14 ovs-ctl --system-id=random|uuid [options] force-reload-kmod
15 ovs-ctl [--protocol=protocol] [--sport=sport] [--dport=dport]
16 enable-protocol
17 ovs-ctl help | -h | --help
18 ovs-ctl --version
19
21 The ovs-ctl program starts, stops, and checks the status of Open
22 vSwitch daemons. It is not meant to be invoked directly by system
23 administrators but to be called internally by system startup scripts.
24 Each of ovs-ctl's commands is described separately below.
26
28 The start command starts Open vSwitch. It performs the following
29 tasks:
30 1. Loads the Open vSwitch kernel module. If this fails, and the
32 Linux bridge module is loaded but no bridges exist, it tries to
33 unload the bridge module and tries loading the Open vSwitch ker‐
34 nel module again. (This is because the Open vSwitch kernel mod‐
35 ule cannot coexist with the Linux bridge module before 2.6.37.)
36 The start command skips the following steps if ovsdb-server is already
38 running:
39 2. If the Open vSwitch database file does not exist, it creates it.
41 If the database does exist, but it has an obsolete version, it
42 upgrades it to the latest schema.
43 3. Starts ovsdb-server.
45 4. Initializes a few values inside the database.
47 5. If the --delete-bridges option was used, deletes all of the
49 bridges from the database.
50 The start command skips the following step if ovs-vswitchd is already
52 running:
53 6. Starts ovs-vswitchd.
55 Options
57 Several command-line options influence the start command's behavior.
58 Some form of the following option should ordinarily be specified:
59 --system-id=uuid
61 --system-id=random
62 This specifies a unique system identifier to store into exter‐
63 nal-ids:system-id in the database's Open_vSwitch table. Remote
64 managers that talk to the Open vSwitch database server over net‐
65 work protocols use this value to identify and distinguish Open
66 vSwitch instances, so it should be unique (at least) within OVS
67 instances that will connect to a single controller.
68 When random is specified, ovs-ctl will generate a random ID that
70 persists from one run to another (stored in a file). When
71 another string is specified ovs-ctl uses it literally.
72 The following options should be specified if the defaults are not suit‐
74 able:
75 --system-type=type
77 --system-version=version
78 Sets the value to store in the system-type and system-version
79 columns, respectively, in the database's Open_vSwitch table.
80 Remote managers may use these values to determine the kind of
81 system to which they are connected (primarily for display to
82 human administrators).
83 When not specified, ovs-ctl uses values from the optional sys‐
85 tem-type.conf and system-version.conf files(see section FILES)
86 or it uses the lsb_release program, if present, to provide rea‐
87 sonable defaults.
88 The following options are also likely to be useful:
90 --external-id="name=value"
92 Sets external-ids:name to value in the database's Open_vSwitch
93 table. Specifying this option multiple times adds multiple key-
94 value pairs.
95 --delete-bridges
97 Ordinarily Open vSwitch bridges persist from one system boot to
98 the next, as long as the database is preserved. Some environ‐
99 ments instead expect to re-create all of the bridges and other
100 configuration state on every boot. This option supports that,
101 by deleting all Open vSwitch bridges after starting ovsdb-server
102 but before starting ovs-vswitchd.
103 The following options are less important:
105 --daemon-cwd=directory
107 Specifies the current working directory that the OVS daemons
108 should run from. The default is / (the root directory) if this
109 option is not specified. (This option is useful because most
110 systems create core files in a process's current working direc‐
111 tory and because a file system that is in use as a process's
112 current working directory cannot be unmounted.)
113 --no-force-corefiles
115 By default, ovs-ctl enables core dumps for the OVS daemons.
116 This option disables that behavior.
117 --no-mlockall
119 By default ovs-ctl passes --mlockall to ovs-vswitchd, requesting
120 that it lock all of its virtual memory, preventing it from being
121 paged to disk. This option suppresses that behavior.
122 --ovsdb-server-priority=niceness
124 --ovs-vswitchd-priority=niceness
125 Sets the nice(1) level used for each daemon. All of them
126 default to -10.
127 --ovsdb-server-wrapper=wrapper
129 --ovs-vswitchd-wrapper=wrapper
130 Configures the specified daemon to run under wrapper, which is
131 one of the following:
132 valgrind
134 Run the daemon under valgrind(1), if it is installed,
135 logging to daemon.valgrind.log.pid in the log directory.
136 strace Run the daemon under strace(1), if it is installed, log‐
138 ging to daemon.strace.log.pid in the log directory.
139 glibc Enable GNU C library features designed to find memory
141 errors.
142 By default, no wrapper is used.
144 Each of the wrappers can expose bugs in Open vSwitch that lead
146 to incorrect operation, including crashes. The valgrind and
147 strace wrappers greatly slow daemon operations so they should
148 not be used in production. They also produce voluminous logs
149 that can quickly fill small disk partitions. The glibc wrapper
150 is less resource-intensive but still somewhat slows the daemons.
151 The following options control file locations. They should only be used
153 if the default locations cannot be used. See FILES, below, for more
154 information.
155 --db-file=file
157 Overrides the file name for the OVS database.
158 --db-sock=socket
160 Overrides the file name for the Unix domain socket used to con‐
161 nect to ovsdb-server.
162 --db-schema=schema
164 Overrides the file name for the OVS database schema.
165 --extra-dbs=file
167 Adds file as an extra database for ovsdb-server to serve out.
168 Multiple space-separated file names may also be specified. file
169 should begin with /; if it does not, then it will be taken as
170 relative to dbdir.
171
173 The stop command does not unload the Open vSwitch kernel modules.
174 This command does nothing and finishes successfully if the OVS daemons
176 aren't running.
177
179 The restart command performs a stop followed by a start command. The
180 command can take the same options as that of the start command. In
181 addition, it saves and restores Openflow flows for each individual
182 bridge.
183
185 The status command checks whether the OVS daemons ovs-vswitchd and
186 ovsdb-server are running and prints messages with that information. It
187 exits with status 0 if the daemons are running, 1 otherwise.
188
190 The version command runs ovsdb-server --version and ovs-vswitchd --ver‐
191 sion.
192
194 The force-reload-kmod command allows upgrading the Open vSwitch kernel
195 module without rebooting. It performs the following tasks:
196 1. Gets a list of OVS ``internal'' interfaces, that is, network
198 devices implemented by Open vSwitch. The most common examples
199 of these are bridge ``local ports''.
200 2. Saves the Openflow flows of each bridge.
202 3. Stops the Open vSwitch daemons, as if by a call to ovs-ctl stop.
204 4. Saves the kernel configuration state of the OVS internal inter‐
206 faces listed in step 1, including IP and IPv6 addresses and
207 routing table entries.
208 5. Unloads the Open vSwitch kernel module (including the bridge
210 compatibility module if it is loaded).
211 6. Starts OVS back up, as if by a call to ovs-ctl start. This
213 reloads the kernel module, restarts the OVS daemons and finally
214 restores the saved Openflow flows.
215 7. Restores the kernel configuration state that was saved in step
217 4.
218 8. Checks for daemons that may need to be restarted because they
220 have packet sockets that are listening on old instances of Open
221 vSwitch kernel interfaces and, if it finds any, prints a warning
222 on stdout. DHCP is a common example: if the ISC DHCP client is
223 running on an OVS internal interface, then it will have to be
224 restarted after completing the above procedure. (It would be
225 nice if ovs-ctl could restart daemons automatically, but the
226 details are far too specific to a particular distribution and
227 installation.)
228 force-kmod-reload internally stops and starts OVS, so it accepts all of
230 the options accepted by the start command.
231
233 The load-kmod command loads the openvswitch kernel modules if they are
234 not already loaded. This operation also occurs as part of the start
235 command. The motivation for providing the load-kmod command is to allow
236 errors when loading modules to be handled separatetly from other errors
237 that may occur when running the start command.
238 By default the load-kmod command attempts to load the openvswitch ker‐
240 nel module.
241
243 The enable-protocol command checks for rules related to a specified
244 protocol in the system's iptables(8) configuration. If there are no
245 rules specifically related to that protocol, then it inserts a rule to
246 accept the specified protocol.
247 More specifically:
249 · If iptables is not installed or not enabled, this command does
251 nothing, assuming that lack of filtering means that the protocol
252 is enabled.
253 · If the INPUT chain has a rule that matches the specified proto‐
255 col, then this command does nothing, assuming that whatever rule
256 is installed reflects the system administrator's decisions.
257 · Otherwise, this command installs a rule that accepts traffic of
259 the specified protocol.
260 This command normally completes successfully, even if it does nothing.
262 Only the failure of an attempt to insert a rule normally causes it to
263 return an exit code other than 0. The following options control the
264 protocol to be enabled:
265 --protocol=protocol
267 The name of the IP protocol to be enabled, such as gre or tcp.
268 The default is gre.
269 --sport=sport
271 --dport=dport
272 TCP or UDP source or destination port to match. These are
273 optional and allowed only with --protocol=tcp or --protocol=udp.
274
276 Prints a usage message and exits successfully.
277
279 In addition to the options listed for each command above, this option
280 controls the behavior of several of ovs-ctl's commands.
281
283 ovs-ctl exits with status 0 on success and nonzero on failure. The
284 start command is considered to succeed if OVS is already started; the
285 stop command is considered to succeed if OVS is already stopped.
286
288 The following environment variables affect ovs-ctl:
289 PATH ovs-ctl does not hardcode the location of any of the programs
291 that it runs. ovs-ctl will add the sbindir and bindir that were
292 specified at configure time to PATH, if they are not already
293 present.
294 OVS_LOGDIR
296 OVS_RUNDIR
297 OVS_DBDIR
298 OVS_SYSCONFDIR
299 OVS_PKGDATADIR
300 OVS_BINDIR
301 OVS_SBINDIR
302 Setting one of these variables in the environment overrides the
303 respective configure option, both for ovs-ctl itself and for the
304 other Open vSwitch programs that it runs.
305
307 ovs-ctl uses the following files:
308 ovs-lib
310 Shell function library used internally by ovs-ctl. It must be
311 installed in the same directory as ovs-ctl.
312 logdir/daemon.log
314 Per-daemon logfiles.
315 rundir/daemon.pid
317 Per-daemon pidfiles to track whether a daemon is running and
318 with what process ID.
319 pkgdatadir/vswitch.ovsschema
321 The OVS database schema used to initialize the database (use
322 --db-schema to override this location).
323 dbdir/conf.db
325 The OVS database (use --db-file to override this location).
326 rundir/openvswitch/db.sock
328 The Unix domain socket used for local communication with
329 ovsdb-server (use --db-sock to override this location).
330 sysconfdir/openvswitch/system-id.conf
332 The persistent system UUID created and read by --system-id=ran‐
333 dom.
334 sysconfdir/openvswitch/system-type.conf
336 sysconfdir/openvswitch/system-version.conf
337 The system-type and system-version values stored in the data‐
338 base's Open_vSwitch table when not specified as a command-line
339 option.
340
342 The files debian/openvswitch-switch.init and xenserver/etc_init.d_open‐
343 vswitch in the Open vSwitch source distribution are good examples of
344 how to use ovs-ctl.
345
347 README, INSTALL.Linux, ovsdb-server(8), ovs-vswitchd(8).
348Open vSwitch June 2011 ovs-ctl(8)