SYNOPSIS
sarah [ -chqrsvV ] [ -f config_file ]
DESCRIPTION
sarah is an automated log file rotation tool which is meant to replace
older, similar tools such as newsyslog(8). It should be scheduled to
run periodically by cron(8). When it is executed it archives log files
if necessary. As with newsyslog(8), if a log file is determined to
require archiving, sarah rearranges the files so that "logfile" is
empty, and older logfiles are named appropriately to make finding a
particular period's entries as simple as possible. Optionally, the
archived logs can be compressed to save space.
A log may be archived for one or both of two reasons:
1. It is larger than the configured size
2. This is the specific configured date/time for rotation of the log.
The granularity of sarah is dependent on how often it is scheduled to
run by cron(8). Since the program is quite fast, it may be scheduled
to run every minute on most machines without any ill effects; rotation
by date/time assumes this is the case.
When starting up, sarah reads in a configuration file to determine
which logs may potentially be archived. By default, this configuration
file is /usr/local/etc/sarah.conf.
On successful termination, sarah will exit with status 0. If some
failure occurs, sarah will exit with a non-zero status. On FreeBSD
systems, see sysexits(3).
OPTIONS
The following command line options may be used with sarah:
-c Check the config file for errors and exit. If any errors are
detected, sarah will indicate what they are. Otherwise it will
print a status line indicating all is well. When combined with the
-V option (debug mode), an interpreted version of the config file
will be printed to STDOUT before exiting.
-h Print out a help summary and version information then exit.
-f config_file
Instruct sarah to use config_file instead of the default
/usr/local/etc/sarah.conf for its configuration file.
-q Run in quiet mode. sarah will not produce any output; not even
errors. If -v or -V are specified in conjunction with -q, this
option will be ignored.
-r Remove the restriction that sarah must be run as root. In this
-V Place sarah into full debug mode. If both -v and -V are specified,
-V takes precedence.
CONFIGURATION FILE
The sarah configuration file consists of two general statements: direc-
tives and comments. All comments begin with a # character, either at
the beginning of a line or at the end of a directive. Any text after a
# character on a line is treated as a comment.
There are two formats for directives in the sarah configuration file.
The first applies to directives that have optional sub-directives.
This type has the general format of the directive, possibly followed by
an argument, then any sub-directives enclosed in balanced braces ({})
and terminated by a semicolon (;).
The second type of directive does not have any sub-directives (in fact,
this type is normally a sub-directive itself). This type consists of
the directive followed by some number of arguments which are terminated
by a semicolon (;).
Unless otherwise noted, directives may appear more than once within
either the configuration file, or within their respective configuration
block. If such directives appear more than once, the value set by the
last use of the directive will supercede any previous uses. All direc-
tives, except where otherwise noted, may appear within an options block
to set defaults.
Directives which expect sub-directives may be specified with an empty
set of braces in order to unset previous definitions of themselves.
Directives which do not expect sub-directives may be followed immedi-
ately by a semi-colon in order to do the same.
The following directives are supported:
options { directive; [ directive; ... ] };
This directive has no options. It contains directives that set
global configuration options for the behavior of sarah. Each
appearance of the options directive will extinguish any previously
defined options. See the "CONFIGURATION EXAMPLES" section for a
demonstration of this behavior.
The options directive may not appear as a sub-directive of itself
or any other directive.
include { path; [ path; ... ] };
The include directive allows multiple configuration files to be
read from within the main configuration file. The include direc-
tive can contain any number of path names to other config files
that should be read. Each path name should be terminated by a
semi-colon. The contents of the included config files will be read
and interpreted as if they had been inserted in the main config
file at the point of the include directive. Any number of include
rotated if the size limit of the file is exceeded and the current
date/time match the date/time specification for the logfile. If
sizelogic is set to OR, the logfile will be rotated if either or
both requirements are met. The default is AND. The sizelogic
directive may only appear within an options block.
sizemod B|K|M|G|T;
DEPRECATED: This directive has been deprecated and will be removed
in future versions. See the size directive.
The sizemod directive sets the modifier used with values in size
directives (below). B sets size modifier to bytes, K to kilobytes,
M to megabytes, G to gigabytes, and T to terabytes. The sizemod
directive may only appear within an options block.
archivedir path;
By default, logfiles are rotated and archived in the same directory
where they originated. Using the archivedir directive, a new
directory, specified by the required path argument, can be speci-
fied where archives of the logfile will be stored. This may be
useful in situations such as keeping a central repository of old
logs, possibly on an NFS mounted filesystem.
owner user;
group group;
When logfiles are rotated, the archives are given the same owner
and group as the original logfile. Using the owner and group
directives, you can specify a new owner and/or group for the log-
file archives. The required user and group arguments may be either
numeric, or a name which is present in /etc/passwd or /etc/group.
The owner and group directives do not affect the ownership of the
logfile itself, only its archives.
mode mode;
As with ownership, log archives are given the same mode, or permis-
sions, as the original logfile by default. The mode directive may
be used to give the archives different permissions. The required
mode argument must be an absolute (numeric) mode as described by
chmod(1). As with owner and group, the mode directive does not
affect the permissions of the logfile itself, only its archives.
index ordinal|date;
The index directive tells sarah how to name its archive files. If
the ordinal argument is specified (the default) sarah produces num-
bered archives where the index begins at 0 (zero) with the most
recent archive. If the date argument is specified, sarah produces
dated archive files in the format <log>.yyyymmdd-xx where xx is an
index number beginning at 0 (zero) with the first archive rotated
on that date. This allows for multiple rotations of any given file
in one day.
Sarah will always pad index numbers in such a way that all archives
size log_size [b|k|m|g|t];
The size directive sets the size limit for a logfile, beyond which
the logfile will be rotated. The required log_size argument is a
number in bytes by default, but this may be altered by following
the value with an optional magnitude: b for bytes, k for kilobytes,
m for megabytes, g for gigabytes, or t for terabytes.
Each log block requires at least one size or date directive
(below). If neither directive is defined in a log block, or in the
preceding options block, the logfile will never be rotated. The
behavior of sarah when both size and date directives are defined is
controlled by the sizelogic directive.
date { };
This directive opens a new block for defining a date/time specifi-
cation for when the current logfile should be rotated. The date
directive has no parameters, but does have several sub-directives.
Each log block requires at least one date directive, or one size
directive (above). If neither directive is defined in a log block,
or in the preceding options block, the logfile will never be
rotated. The behavior of sarah when both size and date directives
are defined is controlled by the sizelogic directive.
minute time_spec;
hour time_spec;
dow time_spec;
month time_spec;
dom time_spec;
These five directives -- minute, hour, dow (day of week), month,
and dom (day of month) define the date/time specification for the
rotation of a logfile. The required time_spec arguments for each
directive define the various times/dates where a logfile may be
rotated.
Permitted values for the directives are as follows:
field allowed values
----- --------------
minute 0-59
hour 0-23
dom 0-31 (0 means "last day of the month")
month 1-12
dow 0-7 (0 and 7 are Sunday)
An argument may be an asterisk (*) which stands for "first-last".
Ranges are allowed. Ranges are two numbers separated by a hyphen.
The specified range is inclusive. For example, 8-11 for the hours
directive specifies rotation at 8, 9, 10, and 11.
Lists of numbers are also allowed. A list is a set of numbers (or
ranges) separated by commas. Examples: "1,2,5,9", "0-4,8-12"
These five directives may only appear within a date block.
flags [ Z ] [ B ];
The flags directive specifies whether any special processing should
be done to the archived logfile. The Z flag will make sarah com-
press the archive files using gzip(1) to save space. The B flag
means that the file is binary, and so the ASCII message which sarah
inserts into a rotated logfile to indicate the file has been
rotated should not be included. Arguments to the flags directive
may be separated by whitespace but this is not required.
pid path_to_pid_file;
This directive specifies the file to read to find the PID of the
daemon process that writes to the current logfile. If this is set,
then the signal set by the signal directive is sent to the PID read
from this file upon completion of the rotation of the current log-
file. If the pid directive is not set, the PID is read from
/var/run/syslog.pid.
signal signal_number;
This directive sets the signal to be sent to the logging daemon
upon completion of the rotation of the current logfile. The
required signal_number argument may be either a numeric signal num-
ber or its alpha equivalent. By default, a SIGHUP will be sent.
CONFIGURATION EXAMPLES
The cron(8) logfile is rotated once a day at midnight and compressed.
A week's worth of archives are kept.
log /var/cron/log {
keep 7;
date {
minute 0;
hour 0;
}
flags Z;
}
The mail log is rotated at least every Monday at midnight, but also
whenever it exceeds 1 megabyte in size. The archives are stored in a
separate location.
options {
sizelogic OR;
};
log /var/log/maillog {
archivedir /depot/logs;
keep 7;
size 1m;
date {
minute 0;
hour 0;
log /usr/local/www/log/access_log {
archivedir /depot/logs;
date {
minute 0;
};
index date;
owner daemon;
group staff;
mode 0644;
pid /usr/local/www/log/httpd.pid;
signal USR1;
};
The formatting of the configuration file used here is arbitrary. As
long as whitespace is maintained around words, any formatting can be
used. The previous example could easily appear like this, if one was
so inclined:
include{/usr/local/etc/cust-rotation.conf;};log
/usr/local/www/log/access_log{archivedir /depot/logs;
date{minute 0;};index date;
owner daemon;group staff;mode 0644;
pid /usr/local/www/log/httpd.pid; signal USR1;};
Sub-directives of the log directive may also be specified within an
options block to set defaults. In the following example, both log
files may be rotated nightly at midnight, but the access_log file will
only be rotated if it is also larger than 100 kilobytes. Both log
files are indexed by date, with 100 archive files kept.
options {
sizelogic AND;
date { minute 0; hour 0; };
index date;
keep 100;
};
log /usr/local/www/log/access_log {
size 100k;
};
log /usr/local/www/log/error_log {
};
Each use of the options directive will obliterate any options set by
previous uses. In the following example, the access_log file is
rotated at midnight every day as well as whenever the file size reaches
100K; it is indexed by date, and 100 copies are kept. By contrast, the
error_log file is only rotated at midnight when it is at least 200
bytes; it is indexed ordinally, and an indefinite number of copies are
kept.
options {
sizelogic OR;
Sub-directives previously set in the options directive, or previously
set within the same log block can be unset by specifying them with no
data. In the following example, the web server access log is rotated
every night at midnight, and the error log is rotated only when it
reaches 100k or more.
options {
sizelogic AND;
date { minute 0; hour 0; };
size 100k;
};
log /usr/local/www/log/access_log {
size;
};
log /usr/local/www/log/error_log {
date {};
};
FILES
/usr/local/etc/sarah.conf sarah configuration file
BUGS
o A mode to force sarah to trim all logs is missing.
o A testing mode is required where no log rotation is done, but ver-
bose output indicates whether logfiles would have been rotated.
AUTHORS
Copyright 2000-2004 Matthew Pounsett (mattp@conundrum.com)
Available at http://prdownloads.sourceforge.net/sarah/
SEE ALSO
gzip(1), syslog(3), syslogd(8), chown(8), newsyslog(8)
MANUAL VERSION
$Id: sarah.pod,v 1.7 2004/02/06 06:41:47 succorso Exp $
sarah 0.9.1b 2004-02-06 SARAH(1)
Man(1) output converted with
man2html