source: trunk/athena/etc/newsyslog/newsyslog.conf.5 @ 11222

.TH NEWSYSLOG.CONF 5 "December 1, 1995" "MIT Athena"
.SH NAME
newsyslog.conf \- configuration files for newsyslog
.SH DESCRIPTION
When starting up, 
.IR newsyslog
reads in a configuration file to determine what actions should be
taken.  By default, the configuation is read from
.IR /etc/athena/newsyslog.conf .
Each line of this file may either describe a particular log file that
should be handled by
.IR newsyslog ,
or define additional information related to processing of the log
files.  Blank lines and lines starting with a ``#'' are ignored.
.SS Log file description lines
Each log file description line has five mandatory fields and two
optional fields describing the log file to handle, with a whitespace
separating each field.  The fields are as follows:
.br
        logfile name
.br
        owner.group of archives (optional)
.br
        mode of logfile & archives
.br
        number of archives
.br
        size of archives
.br
        number of hours
.br
        flags (optional)
.PP
The
.I logfile name
entry is the name of the system log file to be archived.
.PP
The optional
.I owner.group
entry specifies an ownership and group for the archive file.
The ``.'' is essential, even if the 
.I owner
or
.I group
field is left blank. The
fields may be numeric, or a name which is looked up in 
.I /etc/passwd
or 
.IR /etc/group .
.PP
The
.I number of archives
entry specifies the number of archives to be kept besides the log file
itself.  
.PP
When the size of the logfile reaches 
.I size of 
.IR archives ,
the logfile becomes trimmed as described above.  The size may be any
integer greater than zero and less than 2147483648, in kilobytes.
It may also be ``*'', meaning that the logfile will not be trimmed
unless the
.I number of hours
criterion is met (see below).
.PP
The
.I number of hours
entry specifies the time separation between the trimming of the log
file.  The number may be any integer greater than zero and less than
2147483648.  It may also be ``*'', meaning that the logfile will not
be trimmed unless the
.I size of archives
criterion is met (see above).
.PP
The
.I flags
field specifies any special processing done to the archived log files:
.br
.TP
.B B
means that the file is a binary file, and so the ascii message which
.I newsyslog
normally inserts to indicate the fact that the logs have been turned
over should not be included.
.TP
.B D
indicates that the archived log files should be labelled with the date
when the file was turned over, in the format ``logfile.YYYYMMDD'',
instead of using the usual sequence ``logfile.0'', ``logfile.1''...
.PP
Other flags relating to the processing of the files can be defined in
the file, but one default definition is provided for compatibility:
.TP
.B Z
will compress the archive files to save space using
.IR compress .
This option can be redefined, but the re-definition must appear before
the first log file description line.
.PP
It is possible to specify multiple filtering flags for a single log
file.  In this case, the commands will be executed in order they are
listed in the
.I flags
field.
.SS Filtering and post-processing command definitions
It is possible to define additional flags that describe various
operations which should be performed on the archived log file.
Possible uses for this include defining flags that perform compression
or generation of daily service reports.  The definitions of the
filtering commands consist of:
.br
        the keyword
.RB `` filter ''
.br
        flag letter
.br
        extension added by this filter (optional)
.br
        program to be executed
.br
        command-line arguments (optional)
.PP
The
.I flag letter
is a character which will be used to refer to this kind of filtering
in the log file description lines.  The character is case-insensitive.
Flags must be defined before they are used in a log file description.
.PP
The
.I extension
field describes the filename extension which will be added by this
filter (for example, ``.Z'').  If the field is present, it must start
with a ``.''  and contain no whitespace.  If a filter doesn't change
the filename, this option should be omitted.
.PP
.\" *** The following lines are relevant if USE_EXECVP is defined.
The
.I program
field should be the name of the executable to be run.  If the name is
not a pathname (ie. if it does not contain a slash), the path
specified by the environment variable PATH is searched for an
occurrence of
.IR program .
.\" *** The following lines are relevant if USE_EXECVP is not defined.
.\" The
.\" .I program
.\" field should be a full path to the executable to be run.  No path
.\" search will be performed.
.\" ***
.PP
.I Command line arguments
will be passed to the filtering program.  The name of the logfile will
be passed as the last argument, after all the arguments specified in
the definition.  For instance, if the definition is
.RB `` filter
.B Z .Z /usr/ucb/compress
.BR -f '',
the command that will be executed is
.I /usr/ucb/compress -f
.IR logfile.0 .
.PP
It is possible to specify multiple filtering flags for a single log
file.  In this case, the commands will be executed in order their
flags are specified.
.SS Description of processes to restart
It is possible to define additional flags that describe processes that
should be restarted when the logfile is turned over by sending them a
signal. The processes may be specified either by pid file name,
using ``signal,'' or by process name, using ``signame.'' (The latter
is currently available on SGI only.)
.PP
By default (if no signal flags are specified), a HUP signal
is sent to the process specified by
.IR /etc/syslog.pid ,
which is presumably the running
.IR syslogd .
On the SGI, the HUP signal is sent to the process named ``syslogd,''
as that platform has no
.IR syslog.pid
file.
.PP
The flag definitions have the following fields:
.br
        the keyword
.RB `` signal ''
(or
.RB `` signame '' )
.br
        flag letter
.br
        pidident specifying the pid file (or name of process)
.br
        signal (optional)
.PP
The
.I flag letter
is a character which will be used to refer to this pidident and signal
in the log file description lines.  The character is case-insensitive.
Flags must be defined before they are used in a log file description.
.PP
For the ``signal'' keyword, the
.I pidident
is the name of a file which must contain, on the first line, the
process ID (in ASCII decimal representation) of the process to which a
signal should be sent. For the ``signame'' keyword, it is the name of
the process to be signaled.
.PP
It is possible to specify the
.I signal
which will be sent either by its symbolic name or numerically.  If
this field is omitted, HUP is used.  Note that the same signal will
often have different numbers on various versions of UNIX, so use of
symbolic names is encouraged.  The available signal names include
.\" I commented out all signals which are very unlikely to be useful... "
.BR HUP ,
.BR INT ,
.BR QUIT ,
.\" .BR ILL ,"
.BR ABRT ,
.BR FPE ,
.BR KILL ,
.\".BR BUS ,"
.\".BR SEGV ,"
.\".BR PIPE ,"
.BR ALRM ,
.BR TERM ,
.BR USR1 ,
.BR USR2 ,
.\".BR CHLD ,"
.BR PWR ,
.BR STOP
and
.\".BR TSTP ,"
.BR CONT ,
.\".BR TTIN ,"
.\".BR TTOU ,"
assuming they are implemented by the operating system.  Note that some
of these signals have special meaning to the operating system or
certain application programs, and may not do what you want (ABRT,
KILL, ALRM, STOP and CONT are likely offenders).
.PP
Each specified process will be restarted exactly once, unless none of
the log files it is connected to are actually turned over.  The order
in which the logfiles are turned over is unspecified and shouldn't be
relied upon.  It is possible to specify multiple signal flags for a
single log file.
.SH EXAMPLES
Adding the following line to the configuration file line makes
.I newsyslog
roll over
.I /usr/spool/mqueue/syslog
if it is longer than 50KB, keeping the most recent 5 logfiles with
file mode of 644 (and restarting
.I syslogd
in the process):
.RS
.B /usr/spool/mqueue/syslog 644 5 50 *
.RE
.PP
To also compress the logfiles and insure they are owned by user and group
.IR daemon ,
one would use
.RS
\fB/usr/spool/mqueue/syslog daemon.daemon 644 5 50 * Z\fR
.RE
.PP
Compressing the logfiles using
.I gzip --best -f
.RI < filename >
instead of
.I compress -f
.RI < filename >
can be done as follows, assuming
.I gzip
is installed as
.IR /usr/local/bin/gzip :
.RS
\fBfilter G .gz /usr/local/bin/gzip --best -f
.br
/usr/spool/mqueue/syslog daemon.daemon 644 5 50 * G\fR
.RE
.PP
Multiple filters can be applied to the same file, and they will get
executed in the same order in which their flags are specified.  Notice
that the flags used in this example are
.RB `` SG ''
and not
.RB `` GS '',
because generating the digest must be done before compression!
.RS
\fBfilter G .gz /usr/local/bin/gzip --best -f
.br
filter S /usr/local/bin/sulog-digest bert@mit.edu
.br
/usr/adm/sulog 600 1 10 * SG\fR
.RE
.PP
All of the previous examples restart the
.I syslogd
when a logfile is turned over, but you can specify any program which
specifies a pidfile instead.  For instance, if you are running a
.I httpd
which can be restarted by sending it a HUP signal, and you want to
keep a large number of old 50KB logfiles with filenames like
``access.log.19951201.gz'' (indicating that the logfile was turned
over on December 1, 1995), the logs can be turned over something like
this:
.RS
\fBsignal W /var/httpd/httpd.pid HUP
.br
filter G .gz /usr/local/bin/gzip --best -f
.br
filter H /usr/local/bin/http-digest bert@mit.edu
.br
/var/httpd/access.log www.web 644 1000 50 * DHGW
.br
/var/httpd/error.log www.web 644 1000 50 * DHGW\fR
.RE
.PP
Binary files such as
.I /usr/adm/wtmp
should be tagged with a
.B B
flag to prevent
.I newsyslog
from adding text messages to the file:
.RS
\fB/usr/adm/wtmp 644 3 50 * B\fR
.RE
.SH FILES
/etc/athena/newsyslog.conf
.SH "SEE ALSO"
newsyslog(8), syslogd(8), compress(1), chmod(1), chown(1)