utilities/ovs-appctl.8.in

   1 .\" -*- nroff -*-
   2 .de IQ
   3 .  br
   4 .  ns
   5 .  IP "\\$1"
   6 ..
   7 .TH ovs\-appctl 8 "November 2009" "Open vSwitch" "Open vSwitch Manual"
   8 .ds PN ovs\-appctl
   9 .
  10 .SH NAME
  11 ovs\-appctl \- utility for configuring running Open vSwitch daemons
  12 .
  13 .SH SYNOPSIS
  14 \fBovs\-appctl\fR [\fB\-\-target=\fItarget\fR | \fB\-t\fR \fItarget\fR]
  15 \fIcommand \fR[\fIarg\fR...]
  16 .br
  17 \fBovs\-appctl\fR \-\-help
  18 .br
  19 \fBovs\-appctl\fR \-\-version
  20 .SH DESCRIPTION
  21 Open vSwitch daemons accept certain commands at runtime to control their
  22 behavior and query their settings.  Every daemon accepts a common set of
  23 commands documented under \fBCOMMON COMMANDS\fR below, and
  24 \fBovs\-vswitchd\fR in particular accepts a number of additional
  25 commands documented in \fBovs\-vswitchd\fR(8).
  26 .PP
  27 The \fBovs\-appctl\fR program provides a simple way to invoke these
  28 commands.  The command to be sent is specified on \fBovs\-appctl\fR's
  29 command line as non-option arguments.  \fBovs\-appctl\fR sends the
  30 command and prints the daemon's response on standard output.
  31 .PP
  32 In normal use only a single option is accepted:
  33 .IP "\fB\-t \fItarget\fR"
  34 .IQ "\fB\-\-target=\fItarget\fR"
  35 Tells \fBovs\-appctl\fR which daemon to contact.
  36 .IP
  37 If \fItarget\fR begins with \fB/\fR it must name a Unix domain socket
  38 on which an Open vSwitch daemon is listening for control channel
  39 connections.  By default, each daemon listens on a Unix domain socket
  40 named \fB@RUNDIR@/\fIprogram\fB.\fIpid\fB.ctl\fR, where \fIprogram\fR
  41 is the program's name and \fIpid\fR is its process ID.  For example,
  42 if \fBovs\-vswitchd\fR has PID 123, it would listen on
  43 \fB@RUNDIR@/ovs\-vswitchd.123.ctl\fR.
  44 .IP
  45 Otherwise, \fBovs\-appctl\fR looks for a pidfile, that is, a file
  46 whose contents are the process ID of a running process as a decimal
  47 number, named \fB@RUNDIR@/\fItarget\fB.pid\fR.  (The \fB\-\-pidfile\fR
  48 option makes an Open vSwitch daemon create a pidfile.)
  49 \fBovs\-appctl\fR reads the pidfile, then looks for a Unix socket
  50 named \fB@RUNDIR@/\fItarget\fB.\fIpid\fB.ctl\fR, where \fIpid\fR is
  51 replaced by the process ID read from the pidfile, and uses that file
  52 as if it had been specified directly as the target.
  53 .IP
  54 The default target is \fBovs\-vswitchd\fR.
  55 .
  56 .SH COMMON COMMANDS
  57 Every Open vSwitch daemon supports a common set of commands, which are
  58 documented in this section.
  59 .
  60 .SS GENERAL COMMANDS
  61 These commands display daemon-specific commands and the running version.
  62 Note that these commands are different from the \fB\-\-help\fR and
  63 \fB\-\-version\fR options that return information about the
  64 \fBovs\-appctl\fR utility itself.
  65 .
  66 .IP "\fBhelp\fR"
  67 Lists the commands supported by the target.
  68 .
  69 .IP "\fBversion\fR"
  70 Displays the version and compilation date of the target.
  71 .
  72 .SS LOGGING COMMANDS
  73 Open vSwitch has several log levels.  The highest-severity log level is:
  74 .
  75 .IP "\fBOFF\fR"
  76 No message is ever logged at this level, so setting a logging
  77 facility's log level to \fBOFF\fR disables logging to that facility.
  78 .
  79 .PP
  80 The following log levels, in order of descending severity, are
  81 available:
  82 .
  83 .IP "\fBEMER\fR"
  84 A major failure forced a process to abort.
  85 .IP "\fBERR\fR"
  86 A high-level operation or a subsystem failed.  Attention is
  87 warranted.
  88 .IP "\fBWARN\fR"
  89 A low-level operation failed, but higher-level subsystems may be able
  90 to recover.
  91 .IP "\fBINFO\fR"
  92 Information that may be useful in retrospect when investigating
  93 a problem.
  94 .IP "\fBDBG\fR"
  95 Information useful only to someone with intricate knowledge of the
  96 system, or that would commonly cause too-voluminous log output.  Log
  97 messages at this level are not logged by default.
  98 .
  99 .PP
 100 Every Open vSwitch daemon supports the following commands for examining
 101 and adjusting log levels.
 102 .IP "\fBvlog/list\fR"
 103 Lists the known logging modules and their current levels.
 104 .
 105 .IP "\fBvlog/set\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]"
 106 Sets the logging level for \fImodule\fR in \fIfacility\fR to
 107 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
 108 displayed by the \fB\-\-list\fR option) or the special name \fBANY\fR to
 109 set the logging levels for all modules.  The \fIfacility\fR may be
 110 \fBsyslog\fR, \fBconsole\fR or \fBfile\fR to set the levels for logging to
 111 the system log, console or a file, respectively, or \fBANY\fR to set the
 112 logging levels for all facilities.  If it is omitted,
 113 \fIfacility\fR defaults to \fBANY\fR. Regardless of the log levels set for
 114 \fBfile\fR, logging to a file will not take place unless the target application
 115 was invoked with the \fB\-\-logfile\fR option. The \fIlevel\fR must be one of
 116 \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
 117 \fBdbg\fR, designating the minimum severity of a message for it to be logged.
 118 If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.
 119 .
 120 .IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
 121 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Each time a
 122 message is logged to \fIfacility\fR, \fIpattern\fR determines the
 123 message's formatting.  Most characters in \fIpattern\fR are copied
 124 literally to the log, but special escapes beginning with \fB%\fR are
 125 expanded as follows:
 126 .
 127 .RS
 128 .IP \fB%A\fR
 129 The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
 130 .
 131 .IP \fB%c\fR
 132 The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
 133 the message.
 134 .
 135 .IP \fB%d\fR
 136 The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
 137 .
 138 .IP \fB%d{\fIformat\fB}\fR
 139 The current date and time in the specified \fIformat\fR, which takes
 140 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
 141 .
 142 .IP \fB%m\fR
 143 The message being logged.
 144 .
 145 .IP \fB%N\fR
 146 A serial number for this message within this run of the program, as a
 147 decimal number.  The first message a program logs has serial number 1,
 148 the second one has serial number 2, and so on.
 149 .
 150 .IP \fB%n\fR
 151 A new-line.
 152 .
 153 .IP \fB%p\fR
 154 The level at which the message is logged, e.g. \fBDBG\fR.
 155 .
 156 .IP \fB%P\fR
 157 The program's process ID (pid), as a decimal number.
 158 .
 159 .IP \fB%r\fR
 160 The number of milliseconds elapsed from the start of the application
 161 to the time the message was logged.
 162 .
 163 .IP \fB%%\fR
 164 A literal \fB%\fR.
 165 .RE
 166 .
 167 .IP
 168 A few options may appear between the \fB%\fR and the format specifier
 169 character, in this order:
 170 .
 171 .RS
 172 .IP \fB\-\fR
 173 Left justify the escape's expansion within its field width.  Right
 174 justification is the default.
 175 .
 176 .IP \fB0\fR
 177 Pad the field to the field width with \fB0\fRs.  Padding with spaces
 178 is the default.
 179 .
 180 .IP \fIwidth\fR
 181 A number specifies the minimum field width.  If the escape expands to
 182 fewer characters than \fIwidth\fR then it is padded to fill the field
 183 width.  (A field wider than \fIwidth\fR is not truncated to fit.)
 184 .RE
 185 .
 186 .IP
 187 The default pattern for console and file output is \fB%d{%b %d
 188 %H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
 189 .
 190 .IP "\fBvlog/reopen\fR"
 191 Causes the daemon to close and reopen its log file.  (This
 192 is useful after rotating log files, to cause a new log file to be
 193 used.)
 194 .IP
 195 This has no effect if the target application was not invoked with the
 196 \fB\-\-log\-file\fR option.
 197 .
 198 .SH OPTIONS
 199 .
 200 .so lib/common.man
 201 .
 202 .SH "SEE ALSO"
 203 .
 204 \fBovs\-appctl\fR can control the following daemons:
 205 .BR ovs\-vswitchd (8),
 206 .BR ovs\-controller (8),
 207 .BR ovs\-brcompatd (8).