1OVS-CTL(8)                       Open vSwitch                       OVS-CTL(8)
2
3
4

NAME

6       ovs-ctl - OVS startup helper script
7

SYNOPSIS

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

DESCRIPTION

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
195valgrind: Run the daemon under valgrind(1),  if  it  is  installed,
196           logging to <daemon>.valgrind.log.<pid> in the log directory.
197
198strace: Run the daemon under strace(1), if it is installed, logging
199           to <daemon>.strace.log.<pid> in the log directory.
200
201glibc: 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

OPTIONS

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

EXIT STATUS

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

ENVIRONMENT

376       The following environment variables affect ovs-ctl:
377
378PATH
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
384OVS_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

FILES

392       ovs-ctl uses the following files:
393
394ovs-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

EXAMPLE

433       The file debian/openvswitch-switch.init in the Open vSwitch source dis‐
434       tribution is a good example of how to use ovs-ctl.
435

SEE ALSO

437       README.rst, ovsdb-server(8), ovs-vswitchd(8).
438

AUTHOR

440       The Open vSwitch Development Community
441
443       2016-2023, The Open vSwitch Development Community
444
445
446
447
4483.1                              Jun 08, 2023                       OVS-CTL(8)
Impressum