X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-appctl.8.in;h=440853aef7c197a829df3440aac0f0f47137e848;hb=HEAD;hp=3540693d2db7eabbb3b172eedef00480a2961f7d;hpb=8e34689298c2642301fbb7e5aafa6c1bbfd41cdf;p=sliver-openvswitch.git

diff --git a/utilities/ovs-appctl.8.in b/utilities/ovs-appctl.8.in
index 3540693d2..440853aef 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
@@ -20,7 +20,8 @@ ovs\-appctl \- utility for configuring running Open vSwitch daemons
 .SH DESCRIPTION
 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, and
+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
@@ -51,6 +52,15 @@ 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 COMMON COMMANDS
@@ -72,26 +82,26 @@ 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"
+.IP "\fBoff\fR"
 No message is ever logged at this level, so setting a logging
-facility's log level to \fBOFF\fR disables logging to that facility.
+facility's log level to \fBoff\fR disables logging to that facility.
 .
 .PP
 The following log levels, in order of descending severity, are
 available:
 .
-.IP "\fBEMER\fR"
+.IP "\fBemer\fR"
 A major failure forced a process to abort.
-.IP "\fBERR\fR"
+.IP "\fBerr\fR"
 A high-level operation or a subsystem failed.  Attention is
 warranted.
-.IP "\fBWARN\fR"
+.IP "\fBwarn\fR"
 A low-level operation failed, but higher-level subsystems may be able
 to recover.
-.IP "\fBINFO\fR"
+.IP "\fBinfo\fR"
 Information that may be useful in retrospect when investigating
 a problem.
-.IP "\fBDBG\fR"
+.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.
@@ -102,19 +112,43 @@ 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
+.IP "\fBvlog/set\fR [\fIspec\fR]"
+Sets logging levels.  Without any \fIspec\fR, sets the log level for
+every module and facility 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, designating the
-minimum severity of a message for it to be logged.  If it is omitted,
-\fIlevel\fR defaults to \fBdbg\fR.
+\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:\fIfacility\fB:\fIpattern\fR"
 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Each time a
@@ -127,6 +161,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.
@@ -137,6 +174,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.
@@ -159,6 +213,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
@@ -183,8 +247,12 @@ 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/reopen\fR"
 Causes the daemon to close and reopen its log file.  (This
@@ -198,15 +266,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\-controller (8),
-.BR ovs\-brcompatd (8).
+and
+.BR ovsdb\-server (8).