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

NAME

6       ovs-appctl - utility for configuring running Open vSwitch daemons
7

SYNOPSIS

9       ovs-appctl  [--target=``<target> | ``-t <target>] [--timeout=``<secs> |
10       ``-T <secs>] <command> [<arg>…]
11
12       ovs-appctl --help
13
14       ovs-appctl --version
15

DESCRIPTION

17       Open vSwitch daemons accept certain  commands  at  runtime  to  control
18       their behavior and query their settings.  Every daemon accepts a common
19       set of commands documented under Common Commands below.   Some  daemons
20       support   additional   commands   documented  in  their  own  manpages.
21       ovs-vswitchd in particular accepts a number of additional commands doc‐
22       umented in ovs-vswitchd(8).
23
24       The  ovs-appctl program provides a simple way to invoke these commands.
25       The command to be sent is specified on  ovs-appctl’s  command  line  as
26       non-option arguments.  ovs-appctl sends the command and prints the dae‐
27       mon’s response on standard output.
28
29       In normal use only a single option is accepted:
30
31-t <target> or --target <target>
32
33         Tells ovs-appctl which daemon to contact.
34
35         If <target> begins with / it must name a Unix domain socket on  which
36         an  Open vSwitch daemon is listening for control channel connections.
37         By default, each daemon listens on a Unix domain socket in the rundir
38         (e.g.  /run)  named  <program>.<pid>.ctl, where <program> is the pro‐
39         gram’s  name  and  <pid>  is  its  process  ID.   For   example,   if
40         ovs-vswitchd has PID 123, it would listen on ovs-vswitchd.123.ctl.
41
42         Otherwise,  ovs-appctl  looks in the rundir for a pidfile, that is, a
43         file whose contents are the process ID of a running process as a dec‐
44         imal number, named <target>.pid.  (The --pidfile option makes an Open
45         vSwitch daemon create a pidfile.)  ovs-appctl reads the pidfile, then
46         looks in the rundir for a Unix socket named <target>.<pid>.ctl, where
47         <pid> is replaced by the process ID read from the pidfile,  and  uses
48         that file as if it had been specified directly as the target.
49
50         On  Windows, <target> can be an absolute path to a file that contains
51         a localhost TCP port on which an Open vSwitch daemon is listening for
52         control  channel  connections. By default, each daemon writes the TCP
53         port on which it is listening for control connection  into  the  file
54         <program>.ctl  located inside the rundir. If <target> is not an abso‐
55         lute path, ovs-appctl looks in the rundir  for  a  file  named  <tar‐
56         get>.ctl.  The default target is ovs-vswitchd.
57
58-T <secs> or --timeout=<secs>
59
60         By  default,  or with a <secs> of 0, ovs-appctl waits forever to con‐
61         nect to the daemon and receive a response.  This option  limits  run‐
62         time  to  approximately  <secs>  seconds.   If  the  timeout expires,
63         ovs-appctl exits with a SIGALRM signal.
64

COMMON COMMANDS

66       Every Open vSwitch daemon supports a common set of commands, which  are
67       documented in this section.
68
69   General Commands
70       These  commands  display  daemon-specific commands and the running ver‐
71       sion.  Note that these commands  are  different  from  the  --help  and
72       --version  options that return information about the ovs-appctl utility
73       itself.
74
75list-commands
76
77         Lists the commands supported by the target.
78
79version
80
81         Displays the version and compilation date of the target.
82
83   Logging Commands
84       Open vSwitch has several log levels.  The  highest-severity  log  level
85       is:
86
87off
88
89         No  message is ever logged at this level, so setting a logging desti‐
90         nation’s log level to off disables logging to that destination.
91
92       The following log levels, in order of descending severity,  are  avail‐
93       able:
94
95emer
96
97         A major failure forced a process to abort.
98
99err
100
101         A  high-level  operation  or  a  subsystem failed.  Attention is war‐
102         ranted.
103
104warn
105
106         A low-level operation failed, but higher-level subsystems may be able
107         to recover.
108
109info
110
111         Information  that  may  be  useful in retrospect when investigating a
112         problem.
113
114dbg
115
116         Information useful only to someone with intricate  knowledge  of  the
117         system,  or that would commonly cause too-voluminous log output.  Log
118         messages at this level are not logged by default.
119
120       Every Open vSwitch daemon supports the following commands for examining
121       and adjusting log levels:
122
123vlog/list
124
125         Lists the known logging modules and their current levels.
126
127vlog/list-pattern
128
129         Lists logging pattern used for each destination.
130
131vlog/set [<spec>]
132
133         Sets  logging levels.  Without any <spec>, sets the log level for ev‐
134         ery module and destination to dbg.  Otherwise, <spec> is  a  list  of
135         words  separated  by  spaces or commas or colons, up to one from each
136         category below:
137
138         • A valid module name, as  displayed  by  the  vlog/list  command  on
139           ovs-appctl(8), limits the log level change to the specified module.
140
141syslog,  console, or file, to limit the log level change to only to
142           the system log, to the console, or to a file, respectively.
143
144           On Windows platform, syslog is only useful if <target> was  started
145           with the --syslog-target option (it has no effect otherwise).
146
147off, emer, err, warn, info, or dbg, to control the log level.  Mes‐
148           sages of the given severity or higher will be logged, and  messages
149           of  lower  severity will be filtered out.  off filters out all mes‐
150           sages.
151
152         Case is not significant within <spec>.
153
154         Regardless of the log levels set for file, logging to a file will not
155         take  place  unless  the  target  application  was  invoked  with the
156         --log-file option.
157
158         For compatibility with older versions of OVS, any is accepted  within
159         <spec> but it has no effect.
160
161vlog/set PATTERN:<destination>:<pattern>
162
163         Sets  the  log  pattern  for <destination> to <pattern>.  Each time a
164         message is logged to <destination>,  <pattern>  determines  the  mes‐
165         sage’s formatting.  Most characters in <pattern> are copied literally
166         to the log, but special escapes beginning with % are expanded as fol‐
167         lows:
168
169%A
170
171           The name of the application logging the message, e.g. ovs-vswitchd.
172
173%B
174
175           The RFC5424 syslog PRI of the message.
176
177%c
178
179           The  name of the module (as shown by ovs-appctl --list) logging the
180           message.
181
182%d
183
184           The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS).
185
186%d{<format>}
187
188           The current date and time in the specified  <format>,  which  takes
189           the  same  format as the <template> argument to strftime(3).  As an
190           extension, any # characters in <format> will be replaced  by  frac‐
191           tional  seconds,  e.g. use %H:%M:%S.### for the time to the nearest
192           millisecond.  Sub-second times are only approximate  and  currently
193           decimal places after the third will always be reported as zero.
194
195%D
196
197           The  current  UTC  date  and  time  in  ISO 8601 format (YYYY-MM-DD
198           HH:MM:SS).
199
200%D{<format>}
201
202           The current UTC date and time  in  the  specified  <format>,  which
203           takes  the same format as the <template> argument to strftime``(3).
204           Supports the same extension for sub-second resolution as ``%d{...}.
205
206%E
207
208           The hostname of the node running the application.
209
210%m
211
212           The message being logged.
213
214%N
215
216           A serial number for this message within this run of the program, as
217           a decimal number.  The first message a program logs has serial num‐
218           ber 1, the second one has serial number 2, and so on.
219
220%n
221
222           A new-line.
223
224%p
225
226           The level at which the message is logged, e.g. DBG.
227
228%P
229
230           The program’s process ID (pid), as a decimal number.
231
232%r
233
234           The number of milliseconds elapsed from the start of  the  applica‐
235           tion to the time the message was logged.
236
237%t
238
239           The  subprogram  name, that is, an identifying name for the process
240           or thread that emitted the log message, such  as  monitor  for  the
241           process  used  for  --monitor  or  main  for the primary process or
242           thread in a program.
243
244%T
245
246           The subprogram name enclosed in parentheses, e.g. (monitor), or the
247           empty string for the primary process or thread in a program.
248
249%%
250
251           A literal %.
252
253         A few options may appear between the % and the format specifier char‐
254         acter, in this order:
255
256-
257
258           Left justify the escape’s expansion within its field width.   Right
259           justification is the default.
260
2610
262
263           Pad  the  field to the field width with 0 characters.  Padding with
264           spaces is the default.
265
266         • <width>
267
268           A number specifies the minimum field width.  If the escape  expands
269           to  fewer  characters  than  <width>  then it is padded to fill the
270           field width.  (A field wider than <width> is not truncated to fit.)
271
272         The default pattern for  console  and  file  output  is  %D{%Y-%m-%dT
273         %H:%M:%SZ}|%05N|%c|%p|%m; for syslog output, %05N|%c|%p|%m.
274
275         Daemons  written  in Python (e.g. ovs-xapi-sync) do not allow control
276         over the log pattern.
277
278vlog/set FACILITY:<facility>
279
280         Sets the RFC5424 facility of the log message. <facility> can  be  one
281         of  kern,  user,  mail, daemon, auth, syslog, lpr, news, uucp, clock,
282         ftp, ntp, audit, alert, clock2, local0, local1, local2,  local3,  lo‐
283         cal4, local5, local6 or local7.
284
285vlog/close
286
287         Causes  the  daemon  to  close  its  log  file,  if it is open.  (Use
288         vlog/reopen to reopen it later.)
289
290vlog/reopen
291
292         Causes the daemon to close its log file, if it is open, and then  re‐
293         open  it.   (This  is useful after rotating log files, to cause a new
294         log file to be used.)
295
296         This has no effect if the target application was not invoked with the
297         --log-file option.
298

OPTIONS

300       -h, --help
301              Prints a brief help message to the console.
302
303       -V, --version
304              Prints version information to the console.
305

SEE ALSO

307       ovs-appctl   can   control   all   Open   vSwitch   daemons,  including
308       ovs-vswitchd(8) and ovsdb-server(1).
309

AUTHOR

311       The Open vSwitch Development Community
312
314       2016-2022, The Open vSwitch Development Community
315
316
317
318
3192.17                             Mar 28, 2022                    OVS-APPCTL(8)
Impressum