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 or \fBconsole\fR to set the levels for logging to the
 111 system log or to the console, respectively, or \fBANY\fR to set the
 112 logging levels for both facilities.  If it is omitted,
 113 \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must be one of
 114 \fBoff\fR, \fBemer\fR, \fBerr\fR, \fBwarn\fR, \fBinfo\fR, or
 115 \fBdbg\fR, designating the
 116 minimum severity of a message for it to be logged.  If it is omitted,
 117 \fIlevel\fR defaults to \fBdbg\fR.
 118 .
 119 .IP "\fBvlog/set PATTERN:\fIfacility\fB:\fIpattern\fR"
 120 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Each time a
 121 message is logged to \fIfacility\fR, \fIpattern\fR determines the
 122 message's formatting.  Most characters in \fIpattern\fR are copied
 123 literally to the log, but special escapes beginning with \fB%\fR are
 124 expanded as follows:
 125 .
 126 .RS
 127 .IP \fB%A\fR
 128 The name of the application logging the message, e.g. \fBovs\-vswitchd\fR.
 129 .
 130 .IP \fB%c\fR
 131 The name of the module (as shown by \fBovs\-appctl \-\-list\fR) logging
 132 the message.
 133 .
 134 .IP \fB%d\fR
 135 The current date and time in ISO 8601 format (YYYY\-MM\-DD HH:MM:SS).
 136 .
 137 .IP \fB%d{\fIformat\fB}\fR
 138 The current date and time in the specified \fIformat\fR, which takes
 139 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
 140 .
 141 .IP \fB%m\fR
 142 The message being logged.
 143 .
 144 .IP \fB%N\fR
 145 A serial number for this message within this run of the program, as a
 146 decimal number.  The first message a program logs has serial number 1,
 147 the second one has serial number 2, and so on.
 148 .
 149 .IP \fB%n\fR
 150 A new-line.
 151 .
 152 .IP \fB%p\fR
 153 The level at which the message is logged, e.g. \fBDBG\fR.
 154 .
 155 .IP \fB%P\fR
 156 The program's process ID (pid), as a decimal number.
 157 .
 158 .IP \fB%r\fR
 159 The number of milliseconds elapsed from the start of the application
 160 to the time the message was logged.
 161 .
 162 .IP \fB%%\fR
 163 A literal \fB%\fR.
 164 .RE
 165 .
 166 .IP
 167 A few options may appear between the \fB%\fR and the format specifier
 168 character, in this order:
 169 .
 170 .RS
 171 .IP \fB\-\fR
 172 Left justify the escape's expansion within its field width.  Right
 173 justification is the default.
 174 .
 175 .IP \fB0\fR
 176 Pad the field to the field width with \fB0\fRs.  Padding with spaces
 177 is the default.
 178 .
 179 .IP \fIwidth\fR
 180 A number specifies the minimum field width.  If the escape expands to
 181 fewer characters than \fIwidth\fR then it is padded to fill the field
 182 width.  (A field wider than \fIwidth\fR is not truncated to fit.)
 183 .RE
 184 .
 185 .IP
 186 The default pattern for console output is \fB%d{%b %d
 187 %H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
 188 .
 189 .IP "\fBvlog/reopen\fR"
 190 Causes the daemon to close and reopen its log file.  (This
 191 is useful after rotating log files, to cause a new log file to be
 192 used.)
 193 .IP
 194 This has no effect if the target application was not invoked with the
 195 \fB\-\-log\-file\fR option.
 196 .
 197 .SH OPTIONS
 198 .
 199 .so lib/common.man
 200 .
 201 .SH "SEE ALSO"
 202 .
 203 \fBovs\-appctl\fR can control the following daemons:
 204 .BR ovs\-vswitchd (8),
 205 .BR ovs\-controller (8),
 206 .BR ovs\-brcompatd (8).