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 \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]"
106 Sets the logging level for \fImodule\fR in \fIfacility\fR to
107 \fIlevel\fR. The \fImodule\fR may be any valid module name (as
108 displayed by the \fB\-\-list\fR option) or the special name \fBANY\fR to
109 set the logging levels for all modules. The \fIfacility\fR may be
110 \fBsyslog\fR, \fBconsole\fR or \fBfile\fR to set the levels for logging to
111 the system log, console or a file, respectively, or \fBANY\fR to set the
112 logging levels for all facilities. If it is omitted,
113 \fIfacility\fR defaults to \fBANY\fR. Regardless of the log levels set for
114 \fBfile\fR, logging to a file will not take place unless the target application
115 was invoked with the \fB\-\-logfile\fR option. The \fIlevel\fR must be one of
116 \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
117 \fBdbg\fR, designating the minimum severity of a message for it to be logged.
118 If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.
120 .IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
121 Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Each time a
122 message is logged to \fIfacility\fR, \fIpattern\fR determines the
123 message's formatting. Most characters in \fIpattern\fR are copied
124 literally to the log, but special escapes beginning with \fB%\fR are
129 The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
132 The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
136 The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
138 .IP \fB%d{\fIformat\fB}\fR
139 The current date and time in the specified \fIformat\fR, which takes
140 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
143 The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
145 .IP \fB%D{\fIformat\fB}\fR
146 The current UTC date and time in the specified \fIformat\fR, which takes
147 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
150 The message being logged.
153 A serial number for this message within this run of the program, as a
154 decimal number. The first message a program logs has serial number 1,
155 the second one has serial number 2, and so on.
161 The level at which the message is logged, e.g. \fBDBG\fR.
164 The program's process ID (pid), as a decimal number.
167 The number of milliseconds elapsed from the start of the application
168 to the time the message was logged.
175 A few options may appear between the \fB%\fR and the format specifier
176 character, in this order:
180 Left justify the escape's expansion within its field width. Right
181 justification is the default.
184 Pad the field to the field width with \fB0\fRs. Padding with spaces
188 A number specifies the minimum field width. If the escape expands to
189 fewer characters than \fIwidth\fR then it is padded to fill the field
190 width. (A field wider than \fIwidth\fR is not truncated to fit.)
194 The default pattern for console and file output is \fB%D{%Y-%m-%dT
195 %H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
197 .IP "\fBvlog/reopen\fR"
198 Causes the daemon to close and reopen its log file. (This
199 is useful after rotating log files, to cause a new log file to be
202 This has no effect if the target application was not invoked with the
203 \fB\-\-log\-file\fR option.
211 \fBovs\-appctl\fR can control the following daemons:
212 .BR ovs\-vswitchd (8),
213 .BR ovs\-controller (8),
214 .BR ovs\-brcompatd (8).