]>
Commit | Line | Data |
---|---|---|
064af421 BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
d2cb6c95 | 7 | .TH ovs\-appctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" |
064af421 | 8 | .ds PN ovs\-appctl |
a9b4a41a | 9 | . |
064af421 BP |
10 | .SH NAME |
11 | ovs\-appctl \- utility for configuring running Open vSwitch daemons | |
a9b4a41a | 12 | . |
064af421 | 13 | .SH SYNOPSIS |
4e312e69 | 14 | \fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR] |
c1689e19 | 15 | [\fB\-T \fIsecs\fR | \fB\-\-timeout=\fIsecs\fR] |
3fbe1d30 | 16 | \fIcommand \fR[\fIarg\fR...] |
064af421 | 17 | .br |
c1689e19 | 18 | \fBovs\-appctl \fB\-\-help\fR |
064af421 | 19 | .br |
c1689e19 | 20 | \fBovs\-appctl \fB\-\-version\fR |
064af421 | 21 | .SH DESCRIPTION |
264ecd63 JP |
22 | Open vSwitch daemons accept certain commands at runtime to control their |
23 | behavior and query their settings. Every daemon accepts a common set of | |
300d3e95 BP |
24 | commands documented under \fBCOMMON COMMANDS\fR below. Some daemons |
25 | support additional commands documented in their own manpages. | |
264ecd63 JP |
26 | \fBovs\-vswitchd\fR in particular accepts a number of additional |
27 | commands documented in \fBovs\-vswitchd\fR(8). | |
a9b4a41a | 28 | .PP |
3fbe1d30 BP |
29 | The \fBovs\-appctl\fR program provides a simple way to invoke these |
30 | commands. The command to be sent is specified on \fBovs\-appctl\fR's | |
31 | command line as non-option arguments. \fBovs\-appctl\fR sends the | |
32 | command and prints the daemon's response on standard output. | |
a9b4a41a | 33 | .PP |
3fbe1d30 | 34 | In normal use only a single option is accepted: |
3fbe1d30 BP |
35 | .IP "\fB\-t \fItarget\fR" |
36 | .IQ "\fB\-\-target=\fItarget\fR" | |
37 | Tells \fBovs\-appctl\fR which daemon to contact. | |
38 | .IP | |
39 | If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket | |
40 | on which an Open vSwitch daemon is listening for control channel | |
41 | connections. By default, each daemon listens on a Unix domain socket | |
42 | named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR | |
43 | is the program's name and \fIpid\fR is its process ID. For example, | |
4e312e69 BP |
44 | if \fBovs\-vswitchd\fR has PID 123, it would listen on |
45 | \fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR. | |
3fbe1d30 BP |
46 | .IP |
47 | Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file | |
48 | whose contents are the process ID of a running process as a decimal | |
49 | number, named \fB@RUNDIR@/\fItarget\fB.pid\fR. (The \fB\-\-pidfile\fR | |
50 | option makes an Open vSwitch daemon create a pidfile.) | |
51 | \fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket | |
52 | named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is | |
53 | replaced by the process ID read from the pidfile, and uses that file | |
54 | as if it had been specified directly as the target. | |
55 | .IP | |
a085daef GS |
56 | On Windows, \fItarget\fR can be an absolute path to a file that contains |
57 | a localhost TCP port on which an Open vSwitch daemon is listening | |
58 | for control channel connections. By default, each daemon writes the | |
59 | TCP port on which it is listening for control connection into the file | |
60 | \fIprogram\fB.ctl\fR located inside the configured \fIOVS_RUNDIR\fR | |
61 | directory. If \fItarget\fR is not an absolute path, \fBovs\-appctl\fR | |
62 | looks for a file named \fItarget\fB.ctl\fR in the configured \fIOVS_RUNDIR\fR | |
63 | directory. | |
64 | .IP | |
3fbe1d30 BP |
65 | The default target is \fBovs\-vswitchd\fR. |
66 | . | |
c1689e19 BP |
67 | .IP "\fB\-T \fIsecs\fR" |
68 | .IQ "\fB\-\-timeout=\fIsecs\fR" | |
69 | By default, or with a \fIsecs\fR of \fB0\fR, \fBovs\-appctl\fR waits | |
70 | forever to connect to the daemon and receive a response. This option | |
71 | limits runtime to approximately \fIsecs\fR seconds. If the timeout | |
72 | expires, \fBovs\-appctl\fR exits with a \fBSIGALRM\fR signal. | |
73 | . | |
264ecd63 JP |
74 | .SH COMMON COMMANDS |
75 | Every Open vSwitch daemon supports a common set of commands, which are | |
76 | documented in this section. | |
7d110e96 | 77 | . |
264ecd63 JP |
78 | .SS GENERAL COMMANDS |
79 | These commands display daemon-specific commands and the running version. | |
80 | Note that these commands are different from the \fB\-\-help\fR and | |
81 | \fB\-\-version\fR options that return information about the | |
82 | \fBovs\-appctl\fR utility itself. | |
83 | . | |
91a11f5b | 84 | .IP "\fBlist-commands\fR" |
264ecd63 JP |
85 | Lists the commands supported by the target. |
86 | . | |
87 | .IP "\fBversion\fR" | |
88 | Displays the version and compilation date of the target. | |
89 | . | |
90 | .SS LOGGING COMMANDS | |
91 | Open vSwitch has several log levels. The highest-severity log level is: | |
7d110e96 | 92 | . |
2a3e30b2 | 93 | .IP "\fBoff\fR" |
7d110e96 | 94 | No message is ever logged at this level, so setting a logging |
d5460484 | 95 | destination's log level to \fBoff\fR disables logging to that destination. |
7d110e96 BP |
96 | . |
97 | .PP | |
264ecd63 JP |
98 | The following log levels, in order of descending severity, are |
99 | available: | |
7d110e96 | 100 | . |
2a3e30b2 | 101 | .IP "\fBemer\fR" |
7d110e96 | 102 | A major failure forced a process to abort. |
2a3e30b2 | 103 | .IP "\fBerr\fR" |
7d110e96 BP |
104 | A high-level operation or a subsystem failed. Attention is |
105 | warranted. | |
2a3e30b2 | 106 | .IP "\fBwarn\fR" |
7d110e96 BP |
107 | A low-level operation failed, but higher-level subsystems may be able |
108 | to recover. | |
2a3e30b2 | 109 | .IP "\fBinfo\fR" |
7d110e96 BP |
110 | Information that may be useful in retrospect when investigating |
111 | a problem. | |
2a3e30b2 | 112 | .IP "\fBdbg\fR" |
7d110e96 BP |
113 | Information useful only to someone with intricate knowledge of the |
114 | system, or that would commonly cause too-voluminous log output. Log | |
115 | messages at this level are not logged by default. | |
116 | . | |
117 | .PP | |
264ecd63 JP |
118 | Every Open vSwitch daemon supports the following commands for examining |
119 | and adjusting log levels. | |
3fbe1d30 BP |
120 | .IP "\fBvlog/list\fR" |
121 | Lists the known logging modules and their current levels. | |
122 | . | |
532e1463 AA |
123 | .IP "\fBvlog/list-pattern\fR" |
124 | Lists logging pattern used for each destination. | |
125 | . | |
2a3e30b2 BP |
126 | .IP "\fBvlog/set\fR [\fIspec\fR]" |
127 | Sets logging levels. Without any \fIspec\fR, sets the log level for | |
d5460484 | 128 | every module and destination to \fBdbg\fR. Otherwise, \fIspec\fR is a |
2a3e30b2 BP |
129 | list of words separated by spaces or commas or colons, up to one from |
130 | each category below: | |
131 | . | |
132 | .RS | |
133 | .IP \(bu | |
134 | A valid module name, as displayed by the \fBvlog/list\fR command on | |
135 | \fBovs\-appctl\fR(8), limits the log level change to the specified | |
136 | module. | |
137 | . | |
138 | .IP \(bu | |
139 | \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level | |
140 | change to only to the system log, to the console, or to a file, | |
141 | respectively. | |
5a6af13f GS |
142 | .IP |
143 | On Windows platform, \fBsyslog\fR is accepted as a word and | |
144 | is only useful if the \fItarget\fR was started with the | |
145 | \fB\-\-syslog\-target\fR option (the word has no effect otherwise). | |
2a3e30b2 BP |
146 | . |
147 | .IP \(bu | |
c1a543a8 | 148 | \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or |
2a3e30b2 BP |
149 | \fBdbg\fR, to control the log level. Messages of the given severity |
150 | or higher will be logged, and messages of lower severity will be | |
151 | filtered out. \fBoff\fR filters out all messages. | |
152 | .RE | |
153 | . | |
154 | .IP | |
155 | Case is not significant within \fIspec\fR. | |
156 | .IP | |
157 | Regardless of the log levels set for \fBfile\fR, logging to a file | |
158 | will not take place unless the target application was invoked with the | |
159 | \fB\-\-log\-file\fR option. | |
160 | .IP | |
161 | For compatibility with older versions of OVS, \fBany\fR is accepted as | |
162 | a word but has no effect. | |
3fbe1d30 | 163 | . |
d5460484 GS |
164 | .IP "\fBvlog/set PATTERN:\fIdestination\fB:\fIpattern\fR" |
165 | Sets the log pattern for \fIdestination\fR to \fIpattern\fR. Each time a | |
166 | message is logged to \fIdestination\fR, \fIpattern\fR determines the | |
064af421 BP |
167 | message's formatting. Most characters in \fIpattern\fR are copied |
168 | literally to the log, but special escapes beginning with \fB%\fR are | |
169 | expanded as follows: | |
a9b4a41a | 170 | . |
064af421 BP |
171 | .RS |
172 | .IP \fB%A\fR | |
4e312e69 | 173 | The name of the application logging the message, e.g. \fBovs\-vswitchd\fR. |
a9b4a41a | 174 | . |
afc9f547 HM |
175 | .IP \fB%B\fR |
176 | The RFC5424 syslog PRI of the message. | |
177 | . | |
064af421 | 178 | .IP \fB%c\fR |
4e312e69 | 179 | The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging |
064af421 | 180 | the message. |
a9b4a41a | 181 | . |
064af421 | 182 | .IP \fB%d\fR |
4e312e69 | 183 | The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). |
a9b4a41a | 184 | . |
064af421 BP |
185 | .IP \fB%d{\fIformat\fB}\fR |
186 | The current date and time in the specified \fIformat\fR, which takes | |
187 | the same format as the \fItemplate\fR argument to \fBstrftime\fR(3). | |
2b31d8e7 PI |
188 | As an extension, any \fB#\fR characters in \fIformat\fR will be |
189 | replaced by fractional seconds, e.g. use \fB%H:%M:%S.###\fR for the | |
190 | time to the nearest millisecond. Sub-second times are only | |
191 | approximate and currently decimal places after the third will always | |
192 | be reported as zero. | |
a9b4a41a | 193 | . |
b5d29991 GS |
194 | .IP \fB%D\fR |
195 | The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). | |
196 | . | |
197 | .IP \fB%D{\fIformat\fB}\fR | |
2b31d8e7 PI |
198 | The current UTC date and time in the specified \fIformat\fR, which |
199 | takes the same format as the \fItemplate\fR argument to | |
200 | \fBstrftime\fR(3). Supports the same extension for sub-second | |
201 | resolution as \fB%d{\fR...\fB}\fR. | |
b5d29991 | 202 | . |
afc9f547 HM |
203 | .IP \fB%E\fR |
204 | The hostname of the node running the application. | |
205 | . | |
064af421 BP |
206 | .IP \fB%m\fR |
207 | The message being logged. | |
a9b4a41a | 208 | . |
064af421 BP |
209 | .IP \fB%N\fR |
210 | A serial number for this message within this run of the program, as a | |
211 | decimal number. The first message a program logs has serial number 1, | |
212 | the second one has serial number 2, and so on. | |
a9b4a41a | 213 | . |
064af421 BP |
214 | .IP \fB%n\fR |
215 | A new-line. | |
a9b4a41a | 216 | . |
064af421 BP |
217 | .IP \fB%p\fR |
218 | The level at which the message is logged, e.g. \fBDBG\fR. | |
a9b4a41a | 219 | . |
064af421 BP |
220 | .IP \fB%P\fR |
221 | The program's process ID (pid), as a decimal number. | |
a9b4a41a | 222 | . |
064af421 BP |
223 | .IP \fB%r\fR |
224 | The number of milliseconds elapsed from the start of the application | |
225 | to the time the message was logged. | |
a9b4a41a | 226 | . |
781dee08 BP |
227 | .IP \fB%t\fR |
228 | The subprogram name, that is, an identifying name for the process or | |
229 | thread that emitted the log message, such as \fBmonitor\fR for the | |
230 | process used for \fB\-\-monitor\fR or \fBmain\fR for the primary | |
231 | process or thread in a program. | |
232 | . | |
233 | .IP \fB%T\fR | |
234 | The subprogram name enclosed in parentheses, e.g. \fB(monitor)\fR, or | |
235 | the empty string for the primary process or thread in a program. | |
236 | . | |
064af421 BP |
237 | .IP \fB%%\fR |
238 | A literal \fB%\fR. | |
239 | .RE | |
a9b4a41a | 240 | . |
064af421 BP |
241 | .IP |
242 | A few options may appear between the \fB%\fR and the format specifier | |
243 | character, in this order: | |
a9b4a41a | 244 | . |
064af421 | 245 | .RS |
4e312e69 | 246 | .IP \fB\-\fR |
064af421 BP |
247 | Left justify the escape's expansion within its field width. Right |
248 | justification is the default. | |
a9b4a41a | 249 | . |
064af421 BP |
250 | .IP \fB0\fR |
251 | Pad the field to the field width with \fB0\fRs. Padding with spaces | |
252 | is the default. | |
a9b4a41a | 253 | . |
064af421 BP |
254 | .IP \fIwidth\fR |
255 | A number specifies the minimum field width. If the escape expands to | |
256 | fewer characters than \fIwidth\fR then it is padded to fill the field | |
257 | width. (A field wider than \fIwidth\fR is not truncated to fit.) | |
258 | .RE | |
a9b4a41a | 259 | . |
064af421 | 260 | .IP |
b5d29991 GS |
261 | The default pattern for console and file output is \fB%D{%Y-%m-%dT |
262 | %H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. | |
a9b4a41a | 263 | . |
f26ddb5b | 264 | .IP |
2b02d770 PS |
265 | Daemons written in Python (e.g. \fBovs\-xapi\-sync\fR) do not allow |
266 | control over the log pattern. | |
f26ddb5b | 267 | . |
d69d61c7 GS |
268 | .IP "\fBvlog/set\fR FACILITY:\fIfacility\fR" |
269 | Sets the RFC5424 facility of the log message. \fIfacility\fR can be one of | |
270 | \fBkern\fR, \fBuser\fR, \fBmail\fR, \fBdaemon\fR, \fBauth\fR, \fBsyslog\fR, | |
271 | \fBlpr\fR, \fBnews\fR, \fBuucp\fR, \fBclock\fR, \fBftp\fR, \fBntp\fR, | |
272 | \fBaudit\fR, \fBalert\fR, \fBclock2\fR, \fBlocal0\fR, \fBlocal1\fR, | |
273 | \fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR, \fBlocal5\fR, \fBlocal6\fR or | |
274 | \fBlocal7\fR. | |
275 | . | |
06380128 BP |
276 | .IP "\fBvlog/close\fR" |
277 | Causes the daemon to close its log file, if it is open. (Use | |
278 | \fBvlog/reopen\fR to reopen it later.) | |
279 | . | |
3fbe1d30 | 280 | .IP "\fBvlog/reopen\fR" |
06380128 BP |
281 | Causes the daemon to close its log file, if it is open, and then |
282 | reopen it. (This is useful after rotating log files, to cause a new | |
283 | log file to be used.) | |
a9b4a41a | 284 | .IP |
064af421 | 285 | This has no effect if the target application was not invoked with the |
4e312e69 | 286 | \fB\-\-log\-file\fR option. |
a9b4a41a | 287 | . |
064af421 | 288 | .SH OPTIONS |
a9b4a41a | 289 | . |
064af421 | 290 | .so lib/common.man |
a9b4a41a | 291 | . |
064af421 | 292 | .SH "SEE ALSO" |
a9b4a41a | 293 | . |
f26ddb5b | 294 | \fBovs\-appctl\fR can control all Open vSwitch daemons, including: |
3fbe1d30 | 295 | .BR ovs\-vswitchd (8), |
f26ddb5b BP |
296 | and |
297 | .BR ovsdb\-server (8). |