464 lines
9.3 KiB
Groff
464 lines
9.3 KiB
Groff
.TH svlogd 8
|
|
.SH NAME
|
|
svlogd \- runit's service logging daemon
|
|
.SH SYNOPSIS
|
|
.B svlogd
|
|
[\-tttv] [\-r
|
|
.I c\fR] [\-R
|
|
.I xyz\fR] [\-l
|
|
.I len\fR] [\-b
|
|
.I buflen\fR]
|
|
.I logs
|
|
.SH DESCRIPTION
|
|
.I logs
|
|
consists of one or more arguments, each specifying a directory.
|
|
.P
|
|
.B svlogd
|
|
continuously reads log data from its standard input, optionally filters log
|
|
messages, and writes the data to one or more automatically rotated
|
|
.IR logs .
|
|
.P
|
|
Recent log files can automatically be processed by an arbitrary processor
|
|
program when they are rotated, and
|
|
.B svlogd
|
|
can be told to alert selected log messages to standard error, and through
|
|
udp.
|
|
.P
|
|
.B svlogd
|
|
runs until it sees end-of-file on standard input or is sent a TERM signal,
|
|
see below.
|
|
.SS LOG DIRECTORY
|
|
A log directory
|
|
.I log
|
|
contains some number of old log files, and the current log file
|
|
.IR current .
|
|
Old log files have a file name starting with
|
|
.I @
|
|
followed by a precise timestamp (see the daemontools'
|
|
.B tai64n
|
|
program), indicating when
|
|
.I current
|
|
was rotated and renamed to this file.
|
|
.P
|
|
A log directory additionally contains the lock file
|
|
.IR lock ,
|
|
maybe
|
|
.I state
|
|
and
|
|
.IR newstate ,
|
|
and optionally the file
|
|
.IR config .
|
|
.B svlogd
|
|
creates necessary files if they don't exist.
|
|
.P
|
|
If
|
|
.B svlogd
|
|
has trouble opening a log directory, it prints a warning, and ignores this
|
|
log directory.
|
|
If
|
|
.B svlogd
|
|
is unable to open all log directories given at the command line, it exits
|
|
with an error.
|
|
This can happen on start-up or after receiving a HUP signal.
|
|
.SS LOG FILE ROTATION
|
|
.B svlogd
|
|
appends selected log messages to the
|
|
.I current
|
|
log file.
|
|
If
|
|
.I current
|
|
has
|
|
.I size
|
|
bytes or more (or there is a new-line within the last
|
|
.I len
|
|
of
|
|
.I size
|
|
bytes), or is older than a specified amount of
|
|
.IR time ,
|
|
.I current
|
|
is rotated:
|
|
.P
|
|
.B svlogd
|
|
closes
|
|
.IR current ,
|
|
changes permission of
|
|
.I current
|
|
to 0755, renames
|
|
.I current
|
|
to
|
|
.RI @ timestamp\fR.s,
|
|
and starts with a new empty
|
|
.IR current .
|
|
If
|
|
.B svlogd
|
|
sees
|
|
.I num
|
|
or more old log files in the log directory, it removes the oldest one.
|
|
Note that this doesn't decrease the number of log files if there are
|
|
already more than
|
|
.I num
|
|
log files, this must be done manually, e.g. for keeping 10 log files:
|
|
.P
|
|
ls \-1 \\@* |sort |sed \-ne '10,$p' |xargs rm
|
|
.SS PROCESSOR
|
|
If
|
|
.B svlogd
|
|
is told to process recent log files, it saves
|
|
.I current
|
|
to
|
|
.RI @ timestamp\fR.u,
|
|
feeds
|
|
.RI @ timestamp\fR.u
|
|
through ``sh \-c "\fIprocessor\fR"''
|
|
and writes the output to
|
|
.RI @ timestamp\fR.t.
|
|
If the
|
|
.I processor
|
|
finishes successfully,
|
|
.RI @ timestamp\fR.t
|
|
is renamed to
|
|
.RI @ timestamp\fR.s,
|
|
and
|
|
.RI @ timestamp\fR.u
|
|
is deleted; otherwise
|
|
.RI @ timestamp\fR.t
|
|
is deleted and the
|
|
.I processor
|
|
is started again.
|
|
.B svlogd
|
|
also saves any output that the
|
|
.I processor
|
|
writes to file descriptor 5, and makes that output available on file
|
|
descriptor 4 when running
|
|
.I processor
|
|
on the next log file rotation.
|
|
.P
|
|
A
|
|
.I processor
|
|
is run in the background.
|
|
If
|
|
.B svlogd
|
|
sees a previously started
|
|
.I processor
|
|
still running when trying to start a new one for the same
|
|
.IR log ,
|
|
it blocks until the currently running
|
|
.I processor
|
|
has finished successfully.
|
|
Only the HUP signal works in that situation.
|
|
Note that this may block any program feeding its log data to
|
|
.BR svlogd.
|
|
|
|
.SS CONFIG
|
|
On startup, and after receiving a HUP signal,
|
|
.B svlogd
|
|
checks for each log directory
|
|
.I log
|
|
if the configuration file
|
|
.I log/config
|
|
exists, and if so, reads the file line by line and adjusts configuration for
|
|
.I log
|
|
as follows:
|
|
.P
|
|
If the line is empty, or starts with a ``#'', it is ignored.
|
|
A line of the form
|
|
.TP
|
|
.RI s size
|
|
sets the maximum file size of
|
|
.I current
|
|
when
|
|
.B svlogd
|
|
should rotate the current log file to
|
|
.I size
|
|
bytes.
|
|
Default is 1000000.
|
|
If
|
|
.I size
|
|
is zero,
|
|
.B svlogd
|
|
doesn't rotate log files.
|
|
You should set
|
|
.I size
|
|
to at least (2 *
|
|
.IR len ).
|
|
.TP
|
|
.RI n num
|
|
sets the number of old log files
|
|
.B svlogd
|
|
should maintain to
|
|
.IR num .
|
|
If
|
|
.B svlogd
|
|
sees more that
|
|
.I num
|
|
old log files in
|
|
.I log
|
|
after log file rotation, it deletes the oldest one.
|
|
Default is 10.
|
|
If
|
|
.I num
|
|
is zero,
|
|
.B svlogd
|
|
doesn't remove old log files.
|
|
.TP
|
|
.RI N min
|
|
sets the minimum number of old log files
|
|
.B svlogd
|
|
should maintain to
|
|
.IR min .
|
|
.I min
|
|
must be less than
|
|
.IR num .
|
|
If
|
|
.I min
|
|
is set, and
|
|
.B svlogd
|
|
cannot write to
|
|
.I current
|
|
because the filesystem is full, and it sees more than
|
|
.I min
|
|
old log files, it deletes the oldest one.
|
|
.TP
|
|
.RI t timeout
|
|
sets the maximum age of the
|
|
.I current
|
|
log file when
|
|
.B svlogd
|
|
should rotate the current log file to
|
|
.I timeout
|
|
seconds.
|
|
If
|
|
.I current
|
|
is
|
|
.I timeout
|
|
seconds old, and is not empty,
|
|
.B svlogd
|
|
forces log file rotation.
|
|
.TP
|
|
.RI ! processor
|
|
tells
|
|
.B svlogd
|
|
to feed each recent log file through
|
|
.I processor
|
|
(see above) on log file rotation.
|
|
By default log files are not processed.
|
|
.TP
|
|
.RI u a.b.c.d[:port]
|
|
tells
|
|
.B svlogd
|
|
to transmit the first
|
|
.I len
|
|
characters of selected log messages to the IP address
|
|
.IR a.b.c.d ,
|
|
port number
|
|
.IR port .
|
|
If
|
|
.I port
|
|
isn't set, the default port for syslog is used (514).
|
|
.I len
|
|
can be set through the \-l option, see below.
|
|
If
|
|
.B svlogd
|
|
has trouble sending udp packets, it writes error messages to the log
|
|
directory.
|
|
Attention:
|
|
logging through udp is unreliable, and should be used in private networks
|
|
only.
|
|
.TP
|
|
.RI U a.b.c.d[:port]
|
|
is the same as the
|
|
.I u
|
|
line above, but the log messages are no longer written to the log directory,
|
|
but transmitted through udp only.
|
|
Error messages from
|
|
.B svlogd
|
|
concerning sending udp packages still go to the log directory.
|
|
.TP
|
|
.RI p prefix
|
|
tells
|
|
.B svlogd
|
|
to prefix each line to be written to the log directory, to standard error,
|
|
or through UDP, with
|
|
.IR prefix .
|
|
.P
|
|
If a line starts with a
|
|
.IR \- ,
|
|
.IR + ,
|
|
.IR e ,
|
|
or
|
|
.IR E ,
|
|
.B svlogd
|
|
matches the first
|
|
.I len
|
|
characters of each log message against
|
|
.I pattern
|
|
and acts accordingly:
|
|
.TP
|
|
.RI \- pattern
|
|
the log message is deselected.
|
|
.TP
|
|
.RI + pattern
|
|
the log message is selected.
|
|
.TP
|
|
.RI e pattern
|
|
the log message is selected to be printed to standard error.
|
|
.TP
|
|
.RI E pattern
|
|
the log message is deselected to be printed to standard error.
|
|
.P
|
|
Initially each line is selected to be written to
|
|
.IR log/current .
|
|
Deselected log messages are discarded from
|
|
.IR log .
|
|
Initially each line is deselected to be written to standard err.
|
|
Log messages selected for standard error are written to standard error.
|
|
.SH PATTERN MATCHING
|
|
.B svlogd
|
|
matches a log message against the string
|
|
.I pattern
|
|
as follows:
|
|
.P
|
|
.I pattern
|
|
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
|
|
in the log message one or more times.
|
|
A star before the end of
|
|
.I pattern
|
|
matches any string in the log message that does not include the next
|
|
character in
|
|
.IR pattern .
|
|
A star at the end of
|
|
.I pattern
|
|
matches any string.
|
|
.P
|
|
Timestamps optionally added by
|
|
.B svlogd
|
|
are not considered part of the log message.
|
|
.P
|
|
An
|
|
.B svlogd
|
|
pattern is not a regular expression.
|
|
For example consider a log message like this
|
|
.P
|
|
2005-12-18_09:13:50.97618 tcpsvd: info: pid 1977 from 10.4.1.14
|
|
.P
|
|
The following pattern doesn't match
|
|
.P
|
|
-*pid*
|
|
.P
|
|
because the first star matches up to the first p in tcpsvd, and then the
|
|
match fails because i is not s.
|
|
To match this log message, you can use a pattern like this instead
|
|
.P
|
|
-*: *: pid *
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-t
|
|
timestamp.
|
|
Prefix each selected line with a precise timestamp (see the daemontools'
|
|
.B tai64n
|
|
program) when writing to
|
|
.I log
|
|
or to standard error.
|
|
.TP
|
|
.B \-tt
|
|
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
|
|
or to standard error.
|
|
.TP
|
|
.B \-ttt
|
|
timestamp.
|
|
Prefix each selected line with a human readable, sortable UTC timestamp of
|
|
the form YYYY-MM-DDTHH:MM:SS.xxxxx when writing to
|
|
.I log
|
|
or to standard error.
|
|
.TP
|
|
.B \-r \fIc
|
|
replace.
|
|
.I c
|
|
must be a single character.
|
|
Replace non-printable characters in log messages with
|
|
.IR c .
|
|
Characters are replaced before pattern matching is applied.
|
|
.TP
|
|
.B \-R \fIxyz
|
|
replace charset.
|
|
Additionally to non-printable characters, replace all characters found in
|
|
.I xyz
|
|
with
|
|
.I c
|
|
(default ``_'').
|
|
.TP
|
|
.B \-l \fIlen
|
|
line length.
|
|
Pattern matching applies to the first
|
|
.I len
|
|
characters of a log message only.
|
|
Default is 1000.
|
|
.TP
|
|
.B \-b \fIbuflen
|
|
buffer size.
|
|
Set the size of the buffer
|
|
.B svlogd
|
|
uses when reading from standard input and writing to
|
|
.I logs
|
|
to
|
|
.IR buflen .
|
|
Default is 1024.
|
|
.I buflen
|
|
must be greater than
|
|
.IR len .
|
|
For
|
|
.B svlogd
|
|
instances that process a lot of data in short time, the buffer size should
|
|
be increased to improve performance.
|
|
.TP
|
|
.B \-v
|
|
verbose.
|
|
Print verbose messages to standard error.
|
|
.SH SIGNALS
|
|
If
|
|
.B svlogd
|
|
is sent a HUP signal, it closes and reopens all
|
|
.IR logs ,
|
|
and updates their configuration according to
|
|
.IR log/config .
|
|
If
|
|
.B svlogd
|
|
has trouble opening a log directory, it prints a warning, and discards this
|
|
log directory.
|
|
If
|
|
.B svlogd
|
|
is unable to open all log directories given at the command line, it exits
|
|
with an error.
|
|
.P
|
|
If
|
|
.B svlogd
|
|
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
|
|
subprocesses to finish if any, and exits 0 as soon as possible.
|
|
.P
|
|
If
|
|
.B svlogd
|
|
is sent an ALRM signal, it forces log file rotation for all
|
|
.I logs
|
|
with a non empty
|
|
.I current
|
|
log file.
|
|
.SH SEE ALSO
|
|
sv(8),
|
|
runsv(8),
|
|
chpst(8),
|
|
runit(8),
|
|
runit-init(8),
|
|
runsvdir(8),
|
|
runsvchdir(8)
|
|
.P
|
|
http://smarden.org/runit/
|
|
.SH AUTHOR
|
|
Gerrit Pape <pape@smarden.org>
|