1ovs-appctl(8)                 Open vSwitch Manual                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] [-T secs | --timeout=secs]
10       command [arg...]
11       ovs-appctl --help
12       ovs-appctl --version
13

DESCRIPTION

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
22       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
27       In normal use only a single option is accepted:
28
29       -t target
30       --target=target
31              Tells ovs-appctl which daemon to contact.
32
33              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
41              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
50              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
59              The default target is ovs-vswitchd.
60
61       -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

COMMON COMMANDS

69       Every  Open vSwitch daemon supports a common set of commands, which are
70       documented in this section.
71
72   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
78       list-commands
79              Lists the commands supported by the target.
80
81       version
82              Displays the version and compilation date of the target.
83
84   LOGGING COMMANDS
85       Open  vSwitch  has  several log levels.  The highest-severity log level
86       is:
87
88       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
92       The following log levels, in order of descending severity,  are  avail‐
93       able:
94
95       emer   A major failure forced a process to abort.
96
97       err    A high-level operation or a subsystem failed.  Attention is war‐
98              ranted.
99
100       warn   A low-level operation failed, but higher-level subsystems may be
101              able to recover.
102
103       info   Information  that may be useful in retrospect when investigating
104              a problem.
105
106       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
110       Every Open vSwitch daemon supports the following commands for examining
111       and adjusting log levels.
112
113       vlog/list
114              Lists the known logging modules and their current levels.
115
116       vlog/list-pattern
117              Lists logging pattern used for each destination.
118
119       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
125              ·      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
129              ·      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
133                     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
137              ·      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
142              Case is not significant within spec.
143
144              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
148              For compatibility with older versions of OVS, any is accepted as
149              a word but has no effect.
150
151       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
158              %A     The name of the application  logging  the  message,  e.g.
159                     ovs-vswitchd.
160
161              %B     The RFC5424 syslog PRI of the message.
162
163              %c     The  name  of  the module (as shown by ovs-appctl --list)
164                     logging the message.
165
166              %d     The current date and time in ISO 8601 format  (YYYY-MM-DD
167                     HH:MM:SS).
168
169              %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
179              %D     The  current  UTC  date  and  time  in  ISO  8601  format
180                     (YYYY-MM-DD HH:MM:SS).
181
182              %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
188              %E     The hostname of the node running the application.
189
190              %m     The message being logged.
191
192              %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
197              %n     A new-line.
198
199              %p     The level at which the message is logged, e.g. DBG.
200
201              %P     The program's process ID (pid), as a decimal number.
202
203              %r     The  number of milliseconds elapsed from the start of the
204                     application to the time the message was logged.
205
206              %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
211              %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
215              %%     A literal %.
216
217              A  few options may appear between the % and the format specifier
218              character, in this order:
219
220              -      Left justify the  escape's  expansion  within  its  field
221                     width.  Right justification is the default.
222
223              0      Pad  the  field to the field width with 0s.  Padding with
224                     spaces is the default.
225
226              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
231              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
234              Daemons written in Python (e.g. ovs-xapi-sync) do not allow con‐
235              trol over the log pattern.
236
237       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
243       vlog/close
244              Causes the daemon to close its log file, if it  is  open.   (Use
245              vlog/reopen to reopen it later.)
246
247       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
252              This  has  no  effect  if the target application was not invoked
253              with the --log-file option.
254

OPTIONS

256       -h
257       --help Prints a brief help message to the console.
258
259       -V
260       --version
261              Prints version information to the console.
262

SEE ALSO

264       ovs-appctl  can  control   all   Open   vSwitch   daemons,   including:
265       ovs-vswitchd(8), and ovsdb-server(8).
266
267
268
269Open vSwitch                        2.12.0                       ovs-appctl(8)
Impressum