X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-appctl.8.in;h=440853aef7c197a829df3440aac0f0f47137e848;hb=0ef165ecb57943e17a8ee8270df68ffb8d032e29;hp=3248e2cd795838f8c258f2b1677b6076248ca9bf;hpb=a0bc29a541fc7dc6e20137d5558e2094d614e6ab;p=sliver-openvswitch.git diff --git a/utilities/ovs-appctl.8.in b/utilities/ovs-appctl.8.in index 3248e2cd7..440853aef 100644 --- a/utilities/ovs-appctl.8.in +++ b/utilities/ovs-appctl.8.in @@ -4,26 +4,26 @@ . 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 ovs\-appctl \- utility for configuring running Open vSwitch daemons . .SH SYNOPSIS -\fBovs\-appctl\fR [\fB--target=\fItarget\fR | \fB-t\fR \fItarget\fR] +\fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR] \fIcommand \fR[\fIarg\fR...] .br -\fBovs\-appctl\fR --help +\fBovs\-appctl\fR \-\-help .br -\fBovs\-appctl\fR --version +\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 @@ -40,8 +40,8 @@ on which an Open vSwitch daemon is listening for control channel connections. By default, each daemon listens on a Unix domain socket named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR is the program's name and \fIpid\fR is its process ID. For example, -if \fBovs-vswitchd\fR has PID 123, it would listen on -\fB@RUNDIR@/ovs-vswitchd.123.ctl\fR. +if \fBovs\-vswitchd\fR has PID 123, it would listen on +\fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR. .IP Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file whose contents are the process ID of a running process as a decimal @@ -52,27 +52,103 @@ 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 "\fBhelp\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 +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" +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\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, 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 @@ -83,18 +159,38 @@ expanded as follows: . .RS .IP \fB%A\fR -The name of the application logging the message, e.g. \fBovs-vswitchd\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 name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging the message. . .IP \fB%d\fR -The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS). +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 +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 @@ -126,7 +232,7 @@ A few options may appear between the \fB%\fR and the format specifier character, in this order: . .RS -.IP \fB-\fR +.IP \fB\-\fR Left justify the escape's expansion within its field width. Right justification is the default. . @@ -141,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 @@ -150,23 +260,15 @@ is useful after rotating log files, to cause a new log file to be used.) .IP This has no effect if the target application was not invoked with the -\fB--log-file\fR option. +\fB\-\-log\-file\fR option. . .SH OPTIONS . .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), -.BR ovs\-discover (8). +and +.BR ovsdb\-server (8).