7 .TH ovs\-appctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
11 ovs\-appctl \- utility for configuring running Open vSwitch daemons
14 \fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR]
15 \fIcommand \fR[\fIarg\fR...]
17 \fBovs\-appctl\fR \-\-help
19 \fBovs\-appctl\fR \-\-version
21 Open vSwitch daemons accept certain commands at runtime to control their
22 behavior and query their settings. Every daemon accepts a common set of
23 commands documented under \fBCOMMON COMMANDS\fR below, and
24 \fBovs\-vswitchd\fR in particular accepts a number of additional
25 commands documented in \fBovs\-vswitchd\fR(8).
27 The \fBovs\-appctl\fR program provides a simple way to invoke these
28 commands. The command to be sent is specified on \fBovs\-appctl\fR's
29 command line as non-option arguments. \fBovs\-appctl\fR sends the
30 command and prints the daemon's response on standard output.
32 In normal use only a single option is accepted:
33 .IP "\fB\-t \fItarget\fR"
34 .IQ "\fB\-\-target=\fItarget\fR"
35 Tells \fBovs\-appctl\fR which daemon to contact.
37 If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket
38 on which an Open vSwitch daemon is listening for control channel
39 connections. By default, each daemon listens on a Unix domain socket
40 named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR
41 is the program's name and \fIpid\fR is its process ID. For example,
42 if \fBovs\-vswitchd\fR has PID 123, it would listen on
43 \fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR.
45 Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file
46 whose contents are the process ID of a running process as a decimal
47 number, named \fB@RUNDIR@/\fItarget\fB.pid\fR. (The \fB\-\-pidfile\fR
48 option makes an Open vSwitch daemon create a pidfile.)
49 \fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket
50 named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is
51 replaced by the process ID read from the pidfile, and uses that file
52 as if it had been specified directly as the target.
54 The default target is \fBovs\-vswitchd\fR.
57 Every Open vSwitch daemon supports a common set of commands, which are
58 documented in this section.
61 These commands display daemon-specific commands and the running version.
62 Note that these commands are different from the \fB\-\-help\fR and
63 \fB\-\-version\fR options that return information about the
64 \fBovs\-appctl\fR utility itself.
67 Lists the commands supported by the target.
70 Displays the version and compilation date of the target.
73 Open vSwitch has several log levels. The highest-severity log level is:
76 No message is ever logged at this level, so setting a logging
77 facility's log level to \fBoff\fR disables logging to that facility.
80 The following log levels, in order of descending severity, are
84 A major failure forced a process to abort.
86 A high-level operation or a subsystem failed. Attention is
89 A low-level operation failed, but higher-level subsystems may be able
92 Information that may be useful in retrospect when investigating
95 Information useful only to someone with intricate knowledge of the
96 system, or that would commonly cause too-voluminous log output. Log
97 messages at this level are not logged by default.
100 Every Open vSwitch daemon supports the following commands for examining
101 and adjusting log levels.
102 .IP "\fBvlog/list\fR"
103 Lists the known logging modules and their current levels.
105 .IP "\fBvlog/set\fR [\fIspec\fR]"
106 Sets logging levels. Without any \fIspec\fR, sets the log level for
107 every module and facility to \fBdbg\fR. Otherwise, \fIspec\fR is a
108 list of words separated by spaces or commas or colons, up to one from
113 A valid module name, as displayed by the \fBvlog/list\fR command on
114 \fBovs\-appctl\fR(8), limits the log level change to the specified
118 \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level
119 change to only to the system log, to the console, or to a file,
123 \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
124 \fBdbg\fR, to control the log level. Messages of the given severity
125 or higher will be logged, and messages of lower severity will be
126 filtered out. \fBoff\fR filters out all messages.
130 Case is not significant within \fIspec\fR.
132 Regardless of the log levels set for \fBfile\fR, logging to a file
133 will not take place unless the target application was invoked with the
134 \fB\-\-log\-file\fR option.
136 For compatibility with older versions of OVS, \fBany\fR is accepted as
137 a word but has no effect.
139 .IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
140 Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Each time a
141 message is logged to \fIfacility\fR, \fIpattern\fR determines the
142 message's formatting. Most characters in \fIpattern\fR are copied
143 literally to the log, but special escapes beginning with \fB%\fR are
148 The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
151 The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
155 The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
157 .IP \fB%d{\fIformat\fB}\fR
158 The current date and time in the specified \fIformat\fR, which takes
159 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
162 The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
164 .IP \fB%D{\fIformat\fB}\fR
165 The current UTC date and time in the specified \fIformat\fR, which takes
166 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
169 The message being logged.
172 A serial number for this message within this run of the program, as a
173 decimal number. The first message a program logs has serial number 1,
174 the second one has serial number 2, and so on.
180 The level at which the message is logged, e.g. \fBDBG\fR.
183 The program's process ID (pid), as a decimal number.
186 The number of milliseconds elapsed from the start of the application
187 to the time the message was logged.
194 A few options may appear between the \fB%\fR and the format specifier
195 character, in this order:
199 Left justify the escape's expansion within its field width. Right
200 justification is the default.
203 Pad the field to the field width with \fB0\fRs. Padding with spaces
207 A number specifies the minimum field width. If the escape expands to
208 fewer characters than \fIwidth\fR then it is padded to fill the field
209 width. (A field wider than \fIwidth\fR is not truncated to fit.)
213 The default pattern for console and file output is \fB%D{%Y-%m-%dT
214 %H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
216 .IP "\fBvlog/reopen\fR"
217 Causes the daemon to close and reopen its log file. (This
218 is useful after rotating log files, to cause a new log file to be
221 This has no effect if the target application was not invoked with the
222 \fB\-\-log\-file\fR option.
230 \fBovs\-appctl\fR can control the following daemons:
231 .BR ovs\-vswitchd (8),
232 .BR ovs\-controller (8),
233 .BR ovs\-brcompatd (8).