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 [\fIspec\fR]"
 106 Sets logging levels.  Without any \fIspec\fR, sets the log level for
 107 every module and facility to \fBdbg\fR.  Otherwise, \fIspec\fR is a
 108 list of words separated by spaces or commas or colons, up to one from
 109 each category below:
 110 .
 111 .RS
 112 .IP \(bu
 113 A valid module name, as displayed by the \fBvlog/list\fR command on
 114 \fBovs\-appctl\fR(8), limits the log level change to the specified
 115 module.
 116 .
 117 .IP \(bu
 118 \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR, to limit the log level
 119 change to only to the system log, to the console, or to a file,
 120 respectively.
 121 .
 122 .IP \(bu
 123 \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
 124 \fBdbg\fR, to control the log level.  Messages of the given severity
 125 or higher will be logged, and messages of lower severity will be
 126 filtered out.  \fBoff\fR filters out all messages.
 127 .RE
 128 .
 129 .IP
 130 Case is not significant within \fIspec\fR.
 131 .IP
 132 Regardless of the log levels set for \fBfile\fR, logging to a file
 133 will not take place unless the target application was invoked with the
 134 \fB\-\-log\-file\fR option.
 135 .IP
 136 For compatibility with older versions of OVS, \fBany\fR is accepted as
 137 a word but has no effect.
 138 .
 139 .IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
 140 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Each time a
 141 message is logged to \fIfacility\fR, \fIpattern\fR determines the
 142 message's formatting.  Most characters in \fIpattern\fR are copied
 143 literally to the log, but special escapes beginning with \fB%\fR are
 144 expanded as follows:
 145 .
 146 .RS
 147 .IP \fB%A\fR
 148 The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
 149 .
 150 .IP \fB%c\fR
 151 The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
 152 the message.
 153 .
 154 .IP \fB%d\fR
 155 The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
 156 .
 157 .IP \fB%d{\fIformat\fB}\fR
 158 The current date and time in the specified \fIformat\fR, which takes
 159 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
 160 .
 161 .IP \fB%D\fR
 162 The current UTC date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
 163 .
 164 .IP \fB%D{\fIformat\fB}\fR
 165 The current UTC date and time in the specified \fIformat\fR, which takes
 166 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
 167 .
 168 .IP \fB%m\fR
 169 The message being logged.
 170 .
 171 .IP \fB%N\fR
 172 A serial number for this message within this run of the program, as a
 173 decimal number.  The first message a program logs has serial number 1,
 174 the second one has serial number 2, and so on.
 175 .
 176 .IP \fB%n\fR
 177 A new-line.
 178 .
 179 .IP \fB%p\fR
 180 The level at which the message is logged, e.g. \fBDBG\fR.
 181 .
 182 .IP \fB%P\fR
 183 The program's process ID (pid), as a decimal number.
 184 .
 185 .IP \fB%r\fR
 186 The number of milliseconds elapsed from the start of the application
 187 to the time the message was logged.
 188 .
 189 .IP \fB%%\fR
 190 A literal \fB%\fR.
 191 .RE
 192 .
 193 .IP
 194 A few options may appear between the \fB%\fR and the format specifier
 195 character, in this order:
 196 .
 197 .RS
 198 .IP \fB\-\fR
 199 Left justify the escape's expansion within its field width.  Right
 200 justification is the default.
 201 .
 202 .IP \fB0\fR
 203 Pad the field to the field width with \fB0\fRs.  Padding with spaces
 204 is the default.
 205 .
 206 .IP \fIwidth\fR
 207 A number specifies the minimum field width.  If the escape expands to
 208 fewer characters than \fIwidth\fR then it is padded to fill the field
 209 width.  (A field wider than \fIwidth\fR is not truncated to fit.)
 210 .RE
 211 .
 212 .IP
 213 The default pattern for console and file output is \fB%D{%Y-%m-%dT
 214 %H:%M:%SZ}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
 215 .
 216 .IP "\fBvlog/reopen\fR"
 217 Causes the daemon to close and reopen its log file.  (This
 218 is useful after rotating log files, to cause a new log file to be
 219 used.)
 220 .IP
 221 This has no effect if the target application was not invoked with the
 222 \fB\-\-log\-file\fR option.
 223 .
 224 .SH OPTIONS
 225 .
 226 .so lib/common.man
 227 .
 228 .SH "SEE ALSO"
 229 .
 230 \fBovs\-appctl\fR can control the following daemons:
 231 .BR ovs\-vswitchd (8),
 232 .BR ovs\-controller (8),
 233 .BR ovs\-brcompatd (8).