diff options
Diffstat (limited to 'doc/svlogd.8.html')
| -rw-r--r-- | doc/svlogd.8.html | 194 |
1 files changed, 105 insertions, 89 deletions
diff --git a/doc/svlogd.8.html b/doc/svlogd.8.html index 427147d..0f85815 100644 --- a/doc/svlogd.8.html +++ b/doc/svlogd.8.html @@ -41,52 +41,65 @@ can happen on start-up or after receiving a HUP signal. <h3><a name='sect4'>Log File Rotation</a></h3> <b>svlogd</b> appends selected log messages to the <i>current</i> log file. If <i>current</i> has <i>size</i> -bytes or more (or there is a new-line within the last <i>len</i> of <i>size</i> bytes) -<i>current</i> is rotated: <p> -<b>svlogd</b> closes <i>current</i>, changes permission of <i>current</i> -to 0755, renames <i>current</i> to @<i>timestamp.s,</i> and starts with a new empty <i>current</i>. -If <b>svlogd</b> sees <i>num</i> or more old log files in <i>dir</i>, it removes the oldest -one. +bytes or more (or there is a new-line within the last <i>len</i> of <i>size</i> bytes), +or is older than a specified amount of <i>time</i>, <i>current</i> is rotated: <p> +<b>svlogd</b> +closes <i>current</i>, changes permission of <i>current</i> to 0755, renames <i>current</i> +to @<i>timestamp.s,</i> and starts with a new empty <i>current</i>. If <b>svlogd</b> sees <i>num</i> +or more old log files in <i>dir</i>, it removes the oldest one. <h3><a name='sect5'>Processor</a></h3> -If <b>svlogd</b> is told to process recent log files, it saves <i>current</i> -to @<i>timestamp.u,</i> feeds @<i>timestamp.u</i> through ‘‘sh -c "<i>processor</i>"’’ and writes the -output to @<i>timestamp.t.</i> If the <i>processor</i> finishes successfully, @<i>timestamp.u</i> -is deleted and @<i>timestamp.t</i> is renamed to @<i>timestamp.s,</i> otherwise @<i>timestamp.t</i> -is deleted and the <i>processor</i> is started again. <b>svlogd</b> also saves any output -that the <i>processor</i> writes to file descriptor 5, and makes that output available -on file descriptor 4 when running <i>processor</i> on the next log file rotation. -<p> -A <i>processor</i> is run in the background. If <b>svlogd</b> sees a previously started -<i>processor</i> still running when trying to start a new one for the same <i>log</i>, -it blocks until the currently running <i>processor</i> has finished successfully. -Only the HUP signal works in that situation. Note that this may block any -program feeding its log data to <b>svlogd.</b> +If <b>svlogd</b> +is told to process recent log files, it saves <i>current</i> to @<i>timestamp.u,</i> feeds +@<i>timestamp.u</i> through ‘‘sh -c "<i>processor</i>"’’ and writes the output to @<i>timestamp.t.</i> +If the <i>processor</i> finishes successfully, @<i>timestamp.u</i> is deleted and @<i>timestamp.t</i> +is renamed to @<i>timestamp.s,</i> otherwise @<i>timestamp.t</i> is deleted and the <i>processor</i> +is started again. <b>svlogd</b> also saves any output that the <i>processor</i> writes +to file descriptor 5, and makes that output available on file descriptor +4 when running <i>processor</i> on the next log file rotation. <p> +A <i>processor</i> is run +in the background. If <b>svlogd</b> sees a previously started <i>processor</i> still running +when trying to start a new one for the same <i>log</i>, it blocks until the currently +running <i>processor</i> has finished successfully. Only the HUP signal works in +that situation. Note that this may block any program feeding its log data +to <b>svlogd.</b> <p> <h3><a name='sect6'>Config</a></h3> -On startup, and after receiving -a HUP signal, <b>svlogd</b> checks for each <i>log</i> if the configuration file <i>log/config</i> -exists, and if so, reads the file line by line and adjusts configuration -for <i>log</i> as follows: <p> -If the line is empty, less than two characters long, -or starts with a ‘‘#’’, it is ignored. A line of the form +On startup, and after receiving a HUP signal, <b>svlogd</b> checks +for each <i>log</i> if the configuration file <i>log/config</i> exists, and if so, reads +the file line by line and adjusts configuration for <i>log</i> as follows: <p> +If +the line is empty, less than two characters long, or starts with a ‘‘#’’, it +is ignored. A line of the form <dl> <dt>s<i>size</i> </dt> -<dd>sets the maximum -file size of <i>current</i> when <b>svlogd</b> should rotate the current log file to -<i>size</i> bytes. Default is 1000000. If <i>size</i> is zero, <b>svlogd</b> doesn’t rotate log -files. You should set <i>size</i> to at least (2 * <i>len</i>). </dd> +<dd>sets the maximum file size of <i>current</i> +when <b>svlogd</b> should rotate the current log file to <i>size</i> bytes. Default is +1000000. If <i>size</i> is zero, <b>svlogd</b> doesn’t rotate log files. You should set +<i>size</i> to at least (2 * <i>len</i>). </dd> <dt>n<i>num</i> </dt> -<dd>sets the maximum number -of old log files <b>svlogd</b> should maintain to <i>num</i>. If <b>svlogd</b> sees more that -<i>num</i> old log files in <i>log</i> after log file rotation, it deletes the oldest -one. Default is 10. </dd> +<dd>sets the maximum number of old log files +<b>svlogd</b> should maintain to <i>num</i>. If <b>svlogd</b> sees more that <i>num</i> old log files +in <i>log</i> after log file rotation, it deletes the oldest one. Default is 10. +</dd> + +<dt>N<i>min</i> </dt> +<dd>sets the minimum number of old log files <b>svlogd</b> should maintain to +<i>min</i>. <i>min</i> must be less than <i>num</i>. If <i>min</i> is set, and <b>svlogd</b> cannot write to +<i>current</i> because the filesystem is full, and it sees more than <i>min</i> old log +files, it deletes the oldest one. </dd> + +<dt>t<i>timeout</i> </dt> +<dd>sets the maximum age of the <i>current</i> +log file when <b>svlogd</b> should rotate the current log file to <i>timeout</i> seconds. +If <i>current</i> is <i>timeout</i> seconds old, and is not empty, <b>svlogd</b> forces log +file rotation. </dd> <dt>!<i>processor</i> </dt> -<dd>tells <b>svlogd</b> to feed each recent log file -through <i>processor</i> (see above) on log file rotation. By default log files -are not processed. </dd> +<dd>tells <b>svlogd</b> to feed each recent log file through +<i>processor</i> (see above) on log file rotation. By default log files are not +processed. </dd> <dt>u<i>a.b.c.d[:port]</i> </dt> <dd>tells <b>svlogd</b> to transmit the first <i>len</i> characters @@ -113,89 +126,92 @@ each log message against <i>pattern</i> and acts accordingly: message is deselected. </dd> <dt>+<i>pattern</i> </dt> -<dd>the log message is selected </dd> +<dd>the log message is selected. </dd> <dt>e<i>pattern</i> </dt> -<dd>log -messages matching <i>pattern</i> are printed to standard error. </dd> +<dd>the +log message is selected to be printed to standard error. </dd> <dt>E<i>pattern</i> </dt> -<dd>log messages -not matching <i>pattern</i> are printed to standard error. </dd> +<dd>the log +message is deselected to be printed to standard error. </dd> </dl> <p> Initially each line -is selected. Deselected log messages are discarded from <i>log</i>. +is selected to be written to <i>log/current</i>. Deselected log messages are discarded +from <i>log</i>. Initially each line is deselected to be written to standard err. +Log messages selected for standard error are written to standard error. + <h2><a name='sect7'>Pattern Matching</a></h2> -<b>svlogd</b> -matches a log message against the string <i>pattern</i> as follows: <p> -<i>pattern</i> is -applied to the log message one character by one, starting with the first. -A character not a star (‘‘*’’) and not a plus (‘‘+’’) matches itself. A plus matches -the next character in <i>pattern</i> in the log message one or more times. A star -before the end of <i>pattern</i> matches any string in the log message that does -not include the next character in <i>pattern</i>. A star at the end of <i>pattern</i> -matches any string. <p> -Timestamps optionally added by <b>svlogd</b> are not considered -part of the log message. +<b>svlogd</b> matches a log message against the string <i>pattern</i> +as follows: <p> +<i>pattern</i> is applied to the log message one character by one, +starting with the first. A character not a star (‘‘*’’) and not a plus (‘‘+’’) matches +itself. A plus matches the next character in <i>pattern</i> in the log message +one or more times. A star before the end of <i>pattern</i> matches any string in +the log message that does not include the next character in <i>pattern</i>. A star +at the end of <i>pattern</i> matches any string. <p> +Timestamps optionally added by +<b>svlogd</b> are not considered part of the log message. <h2><a name='sect8'>Options</a></h2> <dl> <dt><b>-t</b> </dt> -<dd>timestamp. Prefix each selected line with -a precise timestamp (see <i><b>tai64n</b>(8)</i>) when writing to <i>log</i> or to standard -error. </dd> +<dd>timestamp. Prefix +each selected line with a precise timestamp (see <i><b>tai64n</b>(8)</i>) when writing +to <i>log</i> or to standard error. </dd> <dt><b>-tt</b> </dt> -<dd>timestamp. Prefix each selected line with a human readable, sortable -UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx when writing to <i>log</i> or -to standard error. </dd> +<dd>timestamp. Prefix each selected line with +a human readable, sortable UTC timestamp of the form YYYY-MM-DD_HH:MM:SS.xxxxx +when writing to <i>log</i> or to standard error. </dd> <dt><b>-r <i>c</b> </i></dt> -<dd>replace. <i>c</i> must be a single character. Replace non-printable -characters in log messages with <i>c</i>. Characters are replaced before pattern -matching is applied. </dd> +<dd>replace. <i>c</i> must be a single +character. Replace non-printable characters in log messages with <i>c</i>. Characters +are replaced before pattern matching is applied. </dd> <dt><b>-R <i>xyz</b> </i></dt> -<dd>replace charset. Additionally to non-printable -characters, replace all characters found in <i>xyz</i> with <i>c</i> (default ‘‘_’’). </dd> +<dd>replace charset. Additionally +to non-printable characters, replace all characters found in <i>xyz</i> with <i>c</i> +(default ‘‘_’’). </dd> -<dt><b>-l <i>len</b> -</i></dt> -<dd>line length. Pattern matching applies to the first <i>len</i> characters of a log -message only. Default is 1000. </dd> +<dt><b>-l <i>len</b> </i></dt> +<dd>line length. Pattern matching applies to the first <i>len</i> +characters of a log message only. Default is 1000. </dd> <dt><b>-b <i>buflen</b> </i></dt> -<dd>buffer size. Set the size of the buffer -<b>svlogd</b> uses when reading from standard input and writing to <i>logs</i> to <i>buflen</i>. -Default is 1024. <i>buflen</i> must be greater than <i>len</i>. </dd> +<dd>buffer size. Set +the size of the buffer <b>svlogd</b> uses when reading from standard input and +writing to <i>logs</i> to <i>buflen</i>. Default is 1024. <i>buflen</i> must be greater than <i>len</i>. +</dd> <dt><b>-v</b> </dt> -<dd>verbose. Print verbose -messages to standard error. </dd> +<dd>verbose. Print verbose messages to standard error. </dd> </dl> <h2><a name='sect9'>Signals</a></h2> -If <b>svlogd</b> is sent a HUP signal, it closes -and reopens all <i>logs</i>, and updates their configuration according to <i>log/config</i>. -If <b>svlogd</b> has trouble opening a log directory, it prints a warning, and -discards this log directory. If <b>svlogd</b> is unable to open all log directories -given at the command line, it exits with an error. <p> -If <b>svlogd</b> is sent a TERM -signal, or if it sees end-of-file on standard input, it stops reading standard -input, processes the data in the buffer, waits for all <i>processor</i> subprocesses -to finish if any, and exits 0 as soon as possible. <p> -If <b>svlogd</b> is sent an -ALRM signal, it forces log file rotation for all <i>logs</i> with a non empty -<i>current</i> log file. +If <b>svlogd</b> is +sent a HUP signal, it closes and reopens all <i>logs</i>, and updates their configuration +according to <i>log/config</i>. If <b>svlogd</b> has trouble opening a log directory, +it prints a warning, and discards this log directory. If <b>svlogd</b> is unable +to open all log directories given at the command line, it exits with an +error. <p> +If <b>svlogd</b> is sent a TERM signal, or if it sees end-of-file on standard +input, it stops reading standard input, processes the data in the buffer, +waits for all <i>processor</i> subprocesses to finish if any, and exits 0 as soon +as possible. <p> +If <b>svlogd</b> is sent an ALRM signal, it forces log file rotation +for all <i>logs</i> with a non empty <i>current</i> log file. <h2><a name='sect10'>See Also</a></h2> -<i>runsv(8)</i>, <i>runsvctrl(8)</i>, <i>runsvstat(8)</i>, <i>chpst(8)</i>, -<i>runit(8)</i>, <i>runit-init(8)</i>, <i>runsvdir(8)</i>, <i>runsvchdir(8)</i>, <i>utmpset(8)</i>, <i>multilog(8)</i> -<p> +<i>runsv(8)</i>, <i>runsvctrl(8)</i>, +<i>runsvstat(8)</i>, <i>chpst(8)</i>, <i>runit(8)</i>, <i>runit-init(8)</i>, <i>runsvdir(8)</i>, <i>runsvchdir(8)</i>, +<i>utmpset(8)</i>, <i>multilog(8)</i> <p> <i>http://smarden.org/runit/</i> <h2><a name='sect11'>Author</a></h2> -Gerrit Pape <pape@smarden.org> <p> +Gerrit Pape <pape@smarden.org> +<p> <hr><p> <a name='toc'><b>Table of Contents</b></a><p> |