utilities/vlogconf.8.in

   1 .TH vlogconf 8 "June 2008" "OpenFlow" "OpenFlow Manual"
   2
   3 .SH NAME
   4 vlogconf \- configuration utility for OpenFlow logging in userspace
   5
   6 .SH SYNOPSIS
   7 \fBvlogconf\fR [\fB-h\fR | \fB--help\fR] [\fItarget\fR...] [\fIaction\fR...]
   8 .sp 1
   9 The available \fItarget\fR options are:
  10 .br
  11 [\fB-a\fR | \fB--all\fR] [\fB-t\fR \fIpid\fR | \fB--target=\fIpid\fR]
  12 .sp 1
  13 The available \fIaction\fR options are:
  14 .br
  15 [\fB-l\fR | \fB--list\fR] [\fB-s\fR
  16 \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] |
  17 \fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]
  18 [\fB-r\fR | \fB--reopen\fR]
  19
  20 .SH DESCRIPTION
  21 The \fBvlogconf\fR program configures the logging system used by
  22 OpenFlow userspace programs.  The logging configuration may be modified
  23 while OpenFlow programs are running.
  24
  25 \fBvlogconf\fR applies one or more actions to each of one or more
  26 target processes.  Targets may be specified as:
  27
  28 .TP
  29 \fB-a\fR, \fB--all\fR
  30 All running processes that \fBvlogconf\fR can control.
  31
  32 .TP
  33 \fB-t \fItarget\fR, \fB--target=\fItarget\fR
  34 The specified \fItarget\fR, which must take one of the following forms:
  35
  36 .RS
  37 .IP \(bu
  38 A PID (process ID).
  39
  40 .IP \(bu
  41 An absolute path (beginning with `/') to the Unix domain socket for a
  42 \fBvlogconf\fR-controllable process.
  43
  44 .IP \(bu
  45 An absolute path (beginning with `/') to a pidfile (created by, e.g.,
  46 passing the \fB-P\fR or \fB--pidfile\fR option to one of the OpenFlow
  47 programs).
  48
  49 .IP \(bu
  50 None of the above, in which case \fItarget\fR prefixed by
  51 \fB@RUNDIR@/\fR must match one of the cases for absolute paths listed
  52 above.  (The default name for a program's pidfile is
  53 \fB@RUNDIR@/\fIprogram\fB.pid\fR, so this means that, say,
  54 \fBsecchan\fR's default pidfile may be referred to simply as
  55 \fBsecchan.pid\fR.)
  56 .RE
  57
  58 .PP
  59 The available actions are:
  60
  61 .TP
  62 \fB-l\fR, \fB--list\fR
  63 Print the list of known modules and their current logging levels to
  64 stdout.
  65
  66 .TP
  67 \fB-s\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
  68
  69 Sets the logging level for \fImodule\fR in \fIfacility\fR to
  70 \fIlevel\fR.  The \fImodule\fR may be any valid module name (as
  71 displayed by the \fB--list\fR option) or the special name \fBANY\fR to
  72 set the logging levels for all modules.  The \fIfacility\fR may be
  73 \fBsyslog\fR or \fBconsole\fR to set the levels for logging to the
  74 system log or to the console, respectively, or \fBANY\fR to set the
  75 logging levels for both facilities.  If it is omitted,
  76 \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must be one of
  77 \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating the
  78 minimum severity of a message for it to be logged.  If it is omitted,
  79 \fIlevel\fR defaults to \fBdbg\fR.
  80
  81 .TP
  82 \fB-s PATTERN:\fIfacility\fB:\fIpattern\fR, \fB--set=PATTERN:\fIfacility\fB:\fIpattern\fR
  83
  84 Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Each time a
  85 message is logged to \fIfacility\fR, \fIpattern\fR determines the
  86 message's formatting.  Most characters in \fIpattern\fR are copied
  87 literally to the log, but special escapes beginning with \fB%\fR are
  88 expanded as follows:
  89
  90 .RS
  91 .TP
  92 \fB%A\fR
  93 The name of the application logging the message, e.g. \fBsecchan\fR.
  94
  95 .TP
  96 \fB%c\fR
  97 The name of the module (as shown by \fBvlogconf --list\fR) logging
  98 the message.
  99
 100 .TP
 101 \fB%d\fR
 102 The current date and time in ISO 8601 format (YYYY-MM-DD HH:MM:SS).
 103
 104 .TP
 105 \fB%d{\fIformat\fB}\fR
 106 The current date and time in the specified \fIformat\fR, which takes
 107 the same format as the \fItemplate\fR argument to \fBstrftime\fR(3).
 108
 109 .TP
 110 \fB%m\fR
 111 The message being logged.
 112
 113 .TP
 114 \fB%N\fR
 115 A serial number for this message within this run of the program, as a
 116 decimal number.  The first message a program logs has serial number 1,
 117 the second one has serial number 2, and so on.
 118
 119 .TP
 120 \fB%n\fR
 121 A new-line.
 122
 123 .TP
 124 \fB%p\fR
 125 The level at which the message is logged, e.g. \fBDBG\fR.
 126
 127 .TP
 128 \fB%P\fR
 129 The program's process ID (pid), as a decimal number.
 130
 131 .TP
 132 \fB%r\fR
 133 The number of milliseconds elapsed from the start of the application
 134 to the time the message was logged.
 135
 136 .TP
 137 \fB%%\fR
 138 A literal \fB%\fR.
 139 .RE
 140
 141 .IP
 142 A few options may appear between the \fB%\fR and the format specifier
 143 character, in this order:
 144
 145 .RS
 146 .TP
 147 \fB-\fR
 148 Left justify the escape's expansion within its field width.  Right
 149 justification is the default.
 150
 151 .TP
 152 \fB0\fR
 153 Pad the field to the field width with \fB0\fRs.  Padding with spaces
 154 is the default.
 155
 156 .TP
 157 \fIwidth\fR
 158 A number specifies the minimum field width.  If the escape expands to
 159 fewer characters than \fIwidth\fR then it is padded to fill the field
 160 width.  (A field wider than \fIwidth\fR is not truncated to fit.)
 161 .RE
 162
 163 .IP
 164 The default pattern for console output is \fB%d{%b %d
 165 %H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
 166
 167 .TP
 168 \fB-r\fR, \fB--reopen\fR
 169 Causes the target application to close and reopen its log file.  (This
 170 is useful after rotating log files, to cause a new log file to be
 171 used.)
 172
 173 .SH OPTIONS
 174 .TP
 175 \fB\-h\fR, \fB\-\^\-help\fR
 176 Prints a brief help message to the console and exits.
 177
 178
 179 .SH "SEE ALSO"
 180
 181 .BR dpctl (8),
 182 .BR secchan (8),
 183 .BR controller (8)