sarah - Syslog Automated Rotation and Archive Handler
sarah [ -chqrsvV ] [ -f config_file ]
sarah is a program that should be scheduled to run periodically by cron(8). sarah is intended to be a replacement for newsyslog(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, ``logfile.0'' has the last period's logs in it, ``logfile.1'' has the next to last periods logs in it, and so on, up to a user-specified number of archived logs. Optionally, the archived logs can be compressed to save space.
A log may be archived for one or both of two reasons:
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. sarah is intended to be much more configurable than other log rotators; new features, plus the consideration that future feature requests would need to be accommodated led to the use of a completely different configuration file format from standard log rotators, such as newsyslog(8).
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).
The following options may be used with sarah:
syslogd(8) so the default
signaling action to take on the completion of the rotation of any logfile
will become no action. Also, if this option is specified the -s switch will be ignored.
syslogd(8)
with the DAEMON facility. Ignored if -r is specified. The -s switch
can be specified in conjunction with -v or -V to copy debugging and
verbose output to syslog.
The sarah configuration file consists of two general statements: directives 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 usually 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 appearance of the directive will be used. All directives, except where otherwise noted, may appear within an options block to set defaults.
The following directives are supported:
Sarah will always pad index numbers in such a way that all archives have the same number of digits in their index, but the minimum possible number of digits is used. For example, if there are 10 maillog archives (maillog.0 through maillog.9) then sarah will use single digits; when the 11th archive is created, sarah will change all the indexes to double digits (maillog.00 through maillog.10); when the 101st archive is created, three digits; and so forth.
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''
Step values can be used in conjunction with ranges. Following a range with ``/<number>'' specifies skips of the number's value within the range. For examples, ``0-23/2'' can be used in the hours directive to specify rotation every other hour. Expanded to a list, this would be ``0,2,4,6,8,10,12,14,16,18,20,22''. Step values can also be used in conjunction with an asterisk. This hours example could be specified ``*/2''.
As soon as one directive in a date block is defined, the date/time will be taken into account in the rotation of a logfile. Leaving any directives within a date block undefined equates to entering a * for those directives.
These five directives may only appear within a date block.
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
whitespace is not required.
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;
sizemod K;
};
log /var/log/maillog {
archivedir /depot/logs;
keep 7;
size 1024;
date {
minute 0;
hour 0;
dow 1;
};
};
A separate config file is loaded and interpreted before the log block for the web server logs is interpreted. The web server access logs are rotated every hour onto a large filesystem (our hypothetical web server is very busy). The archive files are dated, old archives are not deleted, and ownership is changed to allow other staff members to read them. The web server daemon is sent a SIGUSR1 signal.
include {
/usr/local/etc/cust-logs.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;
};
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;
sizemod K;
date { minute 0; hour 0; };
index date;
keep 100;
};
log /usr/local/www/log/access_log {
size 100;
};
log /usr/local/www/log/error_log {
};
/usr/local/etc/sarah.conf sarah configuration file
Copyright 2000, 2001 Matthew Pounsett (mattp@conundrum.com)
Available at ftp://ftp.conundrum.com/pub/sarah/
gzip(1), syslog(3), syslogd(8), chown(8), newsyslog(8)