path: root/man/svlogd.8

.TH svlogd 8
.SH NAME
svlogd \- runit's service logging daemon
.SH SYNOPSIS
.B svlogd
[\-ttv] [\-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
.BR tai64n (8)),
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.
.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.u
is deleted and
.RI @ timestamp\fR.t
is renamed to
.RI @ timestamp\fR.s,
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, less than two characters long, 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.
.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.
.SH OPTIONS
.TP
.B \-t
timestamp.
Prefix each selected line with a precise timestamp (see
.BR tai64n (8))
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 \-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 .
.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
runsv(8),
runsvctrl(8),
runsvstat(8),
chpst(8),
runit(8),
runit-init(8),
runsvdir(8),
runsvchdir(8),
utmpset(8),
multilog(8)
.P
http://smarden.org/runit/
.SH AUTHOR
Gerrit Pape <pape@smarden.org>