X-Git-Url: http://git.cascardo.eti.br/?a=blobdiff_plain;f=utilities%2Fovs-appctl.8.in;h=f477534ebdeb9bac962246cc9a8840658fb16920;hb=5b5c922b0ca64abb4ac63f4467e02fcd2221a51a;hp=86d5a8b05259d5a2408447067710a2fbb5c1cce9;hpb=195c8086244e33ec42fd9fc8354eaedfd849bbba;p=cascardo%2Fovs.git diff --git a/utilities/ovs-appctl.8.in b/utilities/ovs-appctl.8.in index 86d5a8b05..f477534eb 100644 --- a/utilities/ovs-appctl.8.in +++ b/utilities/ovs-appctl.8.in @@ -4,7 +4,7 @@ . ns . IP "\\$1" .. -.TH ovs\-appctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual" +.TH ovs\-appctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" .ds PN ovs\-appctl . .SH NAME @@ -18,12 +18,12 @@ ovs\-appctl \- utility for configuring running Open vSwitch daemons .br \fBovs\-appctl\fR \-\-version .SH DESCRIPTION -Open vSwitch daemons accept certain commands at runtime to control -their behavior and query their settings. Every daemon accepts the -commands for querying and adjusting its logging settings documented -under \fBLOGGING COMMANDS\fR below, and \fBovs\-vswitchd\fR in -particular accepts a number of additional commands documented in -\fBovs\-vswitchd\fR(8). +Open vSwitch daemons accept certain commands at runtime to control their +behavior and query their settings. Every daemon accepts a common set of +commands documented under \fBCOMMON COMMANDS\fR below. Some daemons +support additional commands documented in their own manpages. +\fBovs\-vswitchd\fR in particular accepts a number of additional +commands documented in \fBovs\-vswitchd\fR(8). .PP The \fBovs\-appctl\fR program provides a simple way to invoke these commands. The command to be sent is specified on \fBovs\-appctl\fR's @@ -52,31 +52,110 @@ named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is replaced by the process ID read from the pidfile, and uses that file as if it had been specified directly as the target. .IP +On Windows, \fItarget\fR can be an absolute path to a file that contains +a localhost TCP port on which an Open vSwitch daemon is listening +for control channel connections. By default, each daemon writes the +TCP port on which it is listening for control connection into the file +\fIprogram\fB.ctl\fR located inside the configured \fIOVS_RUNDIR\fR +directory. If \fItarget\fR is not an absolute path, \fBovs\-appctl\fR +looks for a file named \fItarget\fB.ctl\fR in the configured \fIOVS_RUNDIR\fR +directory. +.IP The default target is \fBovs\-vswitchd\fR. . -.SH LOGGING COMMANDS -Every Open vSwitch daemon supports the following commands for -examining and adjusting log levels. +.SH COMMON COMMANDS +Every Open vSwitch daemon supports a common set of commands, which are +documented in this section. +. +.SS GENERAL COMMANDS +These commands display daemon-specific commands and the running version. +Note that these commands are different from the \fB\-\-help\fR and +\fB\-\-version\fR options that return information about the +\fBovs\-appctl\fR utility itself. +. +.IP "\fBlist-commands\fR" +Lists the commands supported by the target. +. +.IP "\fBversion\fR" +Displays the version and compilation date of the target. +. +.SS LOGGING COMMANDS +Open vSwitch has several log levels. The highest-severity log level is: +. +.IP "\fBoff\fR" +No message is ever logged at this level, so setting a logging +destination's log level to \fBoff\fR disables logging to that destination. +. +.PP +The following log levels, in order of descending severity, are +available: +. +.IP "\fBemer\fR" +A major failure forced a process to abort. +.IP "\fBerr\fR" +A high-level operation or a subsystem failed. Attention is +warranted. +.IP "\fBwarn\fR" +A low-level operation failed, but higher-level subsystems may be able +to recover. +.IP "\fBinfo\fR" +Information that may be useful in retrospect when investigating +a problem. +.IP "\fBdbg\fR" +Information useful only to someone with intricate knowledge of the +system, or that would commonly cause too-voluminous log output. Log +messages at this level are not logged by default. . +.PP +Every Open vSwitch daemon supports the following commands for examining +and adjusting log levels. .IP "\fBvlog/list\fR" Lists the known logging modules and their current levels. . -.IP "\fBvlog/set\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]" -Sets the logging level for \fImodule\fR in \fIfacility\fR to -\fIlevel\fR. The \fImodule\fR may be any valid module name (as -displayed by the \fB\-\-list\fR option) or the special name \fBANY\fR to -set the logging levels for all modules. The \fIfacility\fR may be -\fBsyslog\fR or \fBconsole\fR to set the levels for logging to the -system log or to the console, respectively, or \fBANY\fR to set the -logging levels for both facilities. If it is omitted, -\fIfacility\fR defaults to \fBANY\fR. The \fIlevel\fR must be one of -\fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or \fBdbg\fR, designating the -minimum severity of a message for it to be logged. If it is omitted, -\fIlevel\fR defaults to \fBdbg\fR. -. -.IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR" -Sets the log pattern for \fIfacility\fR to \fIpattern\fR. Each time a -message is logged to \fIfacility\fR, \fIpattern\fR determines the +.IP "\fBvlog/list-pattern\fR" +Lists logging pattern used for each destination. +. +.IP "\fBvlog/set\fR [\fIspec\fR]" +Sets logging levels. Without any \fIspec\fR, sets the log level for +every module and destination to \fBdbg\fR. Otherwise, \fIspec\fR is a +list of words separated by spaces or commas or colons, up to one from +each category below: +. +.RS +.IP \(bu +A valid module name, as displayed by the \fBvlog/list\fR command on +\fBovs\-appctl\fR(8), limits the log level change to the specified +module. +. +.IP \(bu +\fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level +change to only to the system log, to the console, or to a file, +respectively. +.IP +On Windows platform, \fBsyslog\fR is accepted as a word and +is only useful if the \fItarget\fR was started with the +\fB\-\-syslog\-target\fR option (the word has no effect otherwise). +. +.IP \(bu +\fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or +\fBdbg\fR, to control the log level. Messages of the given severity +or higher will be logged, and messages of lower severity will be +filtered out. \fBoff\fR filters out all messages. +.RE +. +.IP +Case is not significant within \fIspec\fR. +.IP +Regardless of the log levels set for \fBfile\fR, logging to a file +will not take place unless the target application was invoked with the +\fB\-\-log\-file\fR option. +.IP +For compatibility with older versions of OVS, \fBany\fR is accepted as +a word but has no effect. +. +.IP "\fBvlog/set PATTERN:\fIdestination\fB:\fIpattern\fR" +Sets the log pattern for \fIdestination\fR to \fIpattern\fR. Each time a +message is logged to \fIdestination\fR, \fIpattern\fR determines the message's formatting. Most characters in \fIpattern\fR are copied literally to the log, but special escapes beginning with \fB%\fR are expanded as follows: @@ -85,6 +164,9 @@ expanded as follows: .IP \fB%A\fR The name of the application logging the message, e.g. \fBovs\-vswitchd\fR. . +.IP \fB%B\fR +The RFC5424 syslog PRI of the message. +. .IP \fB%c\fR The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging the message. @@ -95,6 +177,23 @@ The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). .IP \fB%d{\fIformat\fB}\fR The current date and time in the specified \fIformat\fR, which takes the same format as the \fItemplate\fR argument to \fBstrftime\fR(3). +As an extension, any \fB#\fR characters in \fIformat\fR will be +replaced by fractional seconds, e.g. use \fB%H:%M:%S.###\fR for the +time to the nearest millisecond. Sub-second times are only +approximate and currently decimal places after the third will always +be reported as zero. +. +.IP \fB%D\fR +The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS). +. +.IP \fB%D{\fIformat\fB}\fR +The current UTC date and time in the specified \fIformat\fR, which +takes the same format as the \fItemplate\fR argument to +\fBstrftime\fR(3). Supports the same extension for sub-second +resolution as \fB%d{\fR...\fB}\fR. +. +.IP \fB%E\fR +The hostname of the node running the application. . .IP \fB%m\fR The message being logged. @@ -117,6 +216,16 @@ The program's process ID (pid), as a decimal number. The number of milliseconds elapsed from the start of the application to the time the message was logged. . +.IP \fB%t\fR +The subprogram name, that is, an identifying name for the process or +thread that emitted the log message, such as \fBmonitor\fR for the +process used for \fB\-\-monitor\fR or \fBmain\fR for the primary +process or thread in a program. +. +.IP \fB%T\fR +The subprogram name enclosed in parentheses, e.g. \fB(monitor)\fR, or +the empty string for the primary process or thread in a program. +. .IP \fB%%\fR A literal \fB%\fR. .RE @@ -141,8 +250,20 @@ width. (A field wider than \fIwidth\fR is not truncated to fit.) .RE . .IP -The default pattern for console output is \fB%d{%b %d -%H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. +The default pattern for console and file output is \fB%D{%Y-%m-%dT +%H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR. +. +.IP +Daemons written in Python (e.g. \fBovs\-xapi\-sync\fR, +\fBovs\-monitor\-ipsec) do not allow control over the log pattern. +. +.IP "\fBvlog/set\fR FACILITY:\fIfacility\fR" +Sets the RFC5424 facility of the log message. \fIfacility\fR can be one of +\fBkern\fR, \fBuser\fR, \fBmail\fR, \fBdaemon\fR, \fBauth\fR, \fBsyslog\fR, +\fBlpr\fR, \fBnews\fR, \fBuucp\fR, \fBclock\fR, \fBftp\fR, \fBntp\fR, +\fBaudit\fR, \fBalert\fR, \fBclock2\fR, \fBlocal0\fR, \fBlocal1\fR, +\fBlocal2\fR, \fBlocal3\fR, \fBlocal4\fR, \fBlocal5\fR, \fBlocal6\fR or +\fBlocal7\fR. . .IP "\fBvlog/reopen\fR" Causes the daemon to close and reopen its log file. (This @@ -156,16 +277,9 @@ This has no effect if the target application was not invoked with the . .so lib/common.man . -.SH BUGS -. -The protocol used to speak to Open vSwitch daemons does not contain a -quoting mechanism, so command arguments should not generally contain -white space. -. .SH "SEE ALSO" . -\fBovs\-appctl\fR can control the following daemons: +\fBovs\-appctl\fR can control all Open vSwitch daemons, including: .BR ovs\-vswitchd (8), -.BR ovs\-openflowd (8), -.BR ovs\-controller (8), -.BR ovs\-brcompatd (8). +and +.BR ovsdb\-server (8).