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