1ovs-appctl(8) Open vSwitch Manual ovs-appctl(8)
2
6 ovs-appctl - utility for configuring running Open vSwitch daemons
7
9 ovs-appctl [--target=target | -t target] [-T secs | --timeout=secs]
10 command [arg...]
11 ovs-appctl --help
12 ovs-appctl --version
13
15 Open vSwitch daemons accept certain commands at runtime to control
16 their behavior and query their settings. Every daemon accepts a common
17 set of commands documented under COMMON COMMANDS below. Some daemons
18 support additional commands documented in their own manpages.
19 ovs-vswitchd in particular accepts a number of additional commands doc‐
20 umented in ovs-vswitchd(8).
21 The ovs-appctl program provides a simple way to invoke these commands.
23 The command to be sent is specified on ovs-appctl's command line as
24 non-option arguments. ovs-appctl sends the command and prints the dae‐
25 mon's response on standard output.
26 In normal use only a single option is accepted:
28 -t target
30 --target=target
31 Tells ovs-appctl which daemon to contact.
32 If target begins with / it must name a Unix domain socket on
34 which an Open vSwitch daemon is listening for control channel
35 connections. By default, each daemon listens on a Unix domain
36 socket named /var/run/openvswitch/program.pid.ctl, where program
37 is the program's name and pid is its process ID. For example,
38 if ovs-vswitchd has PID 123, it would listen on /var/run/open‐
39 vswitch/ovs-vswitchd.123.ctl.
40 Otherwise, ovs-appctl looks for a pidfile, that is, a file whose
42 contents are the process ID of a running process as a decimal
43 number, named /var/run/openvswitch/target.pid. (The --pidfile
44 option makes an Open vSwitch daemon create a pidfile.)
45 ovs-appctl reads the pidfile, then looks for a Unix socket named
46 /var/run/openvswitch/target.pid.ctl, where pid is replaced by
47 the process ID read from the pidfile, and uses that file as if
48 it had been specified directly as the target.
49 On Windows, target can be an absolute path to a file that con‐
51 tains a localhost TCP port on which an Open vSwitch daemon is
52 listening for control channel connections. By default, each dae‐
53 mon writes the TCP port on which it is listening for control
54 connection into the file program.ctl located inside the config‐
55 ured OVS_RUNDIR directory. If target is not an absolute path,
56 ovs-appctl looks for a file named target.ctl in the configured
57 OVS_RUNDIR directory.
58 The default target is ovs-vswitchd.
60 -T secs
62 --timeout=secs
63 By default, or with a secs of 0, ovs-appctl waits forever to
64 connect to the daemon and receive a response. This option lim‐
65 its runtime to approximately secs seconds. If the timeout
66 expires, ovs-appctl exits with a SIGALRM signal.
67
69 Every Open vSwitch daemon supports a common set of commands, which are
70 documented in this section.
71 GENERAL COMMANDS
73 These commands display daemon-specific commands and the running ver‐
74 sion. Note that these commands are different from the --help and
75 --version options that return information about the ovs-appctl utility
76 itself.
77 list-commands
79 Lists the commands supported by the target.
80 version
82 Displays the version and compilation date of the target.
83 LOGGING COMMANDS
85 Open vSwitch has several log levels. The highest-severity log level
86 is:
87 off No message is ever logged at this level, so setting a logging
89 destination's log level to off disables logging to that destina‐
90 tion.
91 The following log levels, in order of descending severity, are avail‐
93 able:
94 emer A major failure forced a process to abort.
96 err A high-level operation or a subsystem failed. Attention is war‐
98 ranted.
99 warn A low-level operation failed, but higher-level subsystems may be
101 able to recover.
102 info Information that may be useful in retrospect when investigating
104 a problem.
105 dbg Information useful only to someone with intricate knowledge of
107 the system, or that would commonly cause too-voluminous log out‐
108 put. Log messages at this level are not logged by default.
109 Every Open vSwitch daemon supports the following commands for examining
111 and adjusting log levels.
112 vlog/list
114 Lists the known logging modules and their current levels.
115 vlog/list-pattern
117 Lists logging pattern used for each destination.
118 vlog/set [spec]
120 Sets logging levels. Without any spec, sets the log level for
121 every module and destination to dbg. Otherwise, spec is a list
122 of words separated by spaces or commas or colons, up to one from
123 each category below:
124 · A valid module name, as displayed by the vlog/list com‐
126 mand on ovs-appctl(8), limits the log level change to the
127 specified module.
128 · syslog, console, or file, to limit the log level change
130 to only to the system log, to the console, or to a file,
131 respectively.
132 On Windows platform, syslog is accepted as a word and is
134 only useful if the target was started with the --sys‐
135 log-target option (the word has no effect otherwise).
136 · off, emer, err, warn, info, or dbg, to control the log
138 level. Messages of the given severity or higher will be
139 logged, and messages of lower severity will be filtered
140 out. off filters out all messages.
141 Case is not significant within spec.
143 Regardless of the log levels set for file, logging to a file
145 will not take place unless the target application was invoked
146 with the --log-file option.
147 For compatibility with older versions of OVS, any is accepted as
149 a word but has no effect.
150 vlog/set PATTERN:destination:pattern
152 Sets the log pattern for destination to pattern. Each time a
153 message is logged to destination, pattern determines the mes‐
154 sage's formatting. Most characters in pattern are copied liter‐
155 ally to the log, but special escapes beginning with % are
156 expanded as follows:
157 %A The name of the application logging the message, e.g.
159 ovs-vswitchd.
160 %B The RFC5424 syslog PRI of the message.
162 %c The name of the module (as shown by ovs-appctl --list)
164 logging the message.
165 %d The current date and time in ISO 8601 format (YYYY-MM-DD
167 HH:MM:SS).
168 %d{format}
170 The current date and time in the specified format, which
171 takes the same format as the template argument to strf‐
172 time(3). As an extension, any # characters in format
173 will be replaced by fractional seconds, e.g. use
174 %H:%M:%S.### for the time to the nearest millisecond.
175 Sub-second times are only approximate and currently deci‐
176 mal places after the third will always be reported as
177 zero.
178 %D The current UTC date and time in ISO 8601 format
180 (YYYY-MM-DD HH:MM:SS).
181 %D{format}
183 The current UTC date and time in the specified format,
184 which takes the same format as the template argument to
185 strftime(3). Supports the same extension for sub-second
186 resolution as %d{...}.
187 %E The hostname of the node running the application.
189 %m The message being logged.
191 %N A serial number for this message within this run of the
193 program, as a decimal number. The first message a pro‐
194 gram logs has serial number 1, the second one has serial
195 number 2, and so on.
196 %n A new-line.
198 %p The level at which the message is logged, e.g. DBG.
200 %P The program's process ID (pid), as a decimal number.
202 %r The number of milliseconds elapsed from the start of the
204 application to the time the message was logged.
205 %t The subprogram name, that is, an identifying name for the
207 process or thread that emitted the log message, such as
208 monitor for the process used for --monitor or main for
209 the primary process or thread in a program.
210 %T The subprogram name enclosed in parentheses, e.g. (moni‐
212 tor), or the empty string for the primary process or
213 thread in a program.
214 %% A literal %.
216 A few options may appear between the % and the format specifier
218 character, in this order:
219 - Left justify the escape's expansion within its field
221 width. Right justification is the default.
222 0 Pad the field to the field width with 0s. Padding with
224 spaces is the default.
225 width A number specifies the minimum field width. If the
227 escape expands to fewer characters than width then it is
228 padded to fill the field width. (A field wider than
229 width is not truncated to fit.)
230 The default pattern for console and file output is %D{%Y-%m-%dT
232 %H:%M:%SZ}|%05N|%c|%p|%m; for syslog output, %05N|%c|%p|%m.
233 Daemons written in Python (e.g. ovs-xapi-sync) do not allow con‐
235 trol over the log pattern.
236 vlog/set FACILITY:facility
238 Sets the RFC5424 facility of the log message. facility can be
239 one of kern, user, mail, daemon, auth, syslog, lpr, news, uucp,
240 clock, ftp, ntp, audit, alert, clock2, local0, local1, local2,
241 local3, local4, local5, local6 or local7.
242 vlog/close
244 Causes the daemon to close its log file, if it is open. (Use
245 vlog/reopen to reopen it later.)
246 vlog/reopen
248 Causes the daemon to close its log file, if it is open, and then
249 reopen it. (This is useful after rotating log files, to cause a
250 new log file to be used.)
251 This has no effect if the target application was not invoked
253 with the --log-file option.
254
256 -h
257 --help Prints a brief help message to the console.
258 -V
260 --version
261 Prints version information to the console.
262
264 ovs-appctl can control all Open vSwitch daemons, including:
265 ovs-vswitchd(8), and ovsdb-server(8).
266Open vSwitch 2.12.0 ovs-appctl(8)