SARAH(1)

NAME
sarah - Syslog Automated Rotation and Archive Handler

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/pkg/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/pkg/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 mode sarah will not be able to send the HUP signal to 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.

-s  Copy all output (including debugging and verbose mode output) to 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.

-v  Place sarah into verbose mode. In this mode, it will print out each log and its reasons for either trimming the log or skipping it.

-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: 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 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 directives, 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 immediately 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 directive 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 directives may appear in a config file, but none may appear as a sub-directive of any other directive. A nesting limit of 20 includes deep is imposed to prevent recursive includes.

log path { directive; [ directive; ... ] };
    This directive opens a new block defining a new logfile. The required path argument is the path to the logfile to be rotated. The log directive may not appear as a sub-directive of itself or any other directive.

sizelogic AND|OR;
    This directive sets the logic used in determining whether to rotate a logfile when both a date and size limit have been set for the logfile. If sizelogic is set to AND, then the logfile is only 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 specified 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 logfile 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 permissions, 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 numbered 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 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. This also applies for date based archive indexing.

keep integer;
    This configuration directive sets the number of archives to keep for each logfile. The number does not include the logfile itself. If set to 0 (zero) or left undefined, sarah will keep an indefinite number of logfiles (until you run out of disk space).

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 specification 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"

    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 example, "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.

flags [ Z ] [ B ];
    The flags directive specifies whether any special processing should be done to the archived logfile. The Z flag will make sarah compress 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 logfile. If the pid directive is not set, the PID is read from /var/run/syslogd.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 number 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;
         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/pkg/etc/cust-logs.conf;
   };
   log /usr/pkg/www/log/access_log {
      archivedir /depot/logs;
      date {
         minute 0;
      };
      index date;
      owner daemon;
      group staff;
      mode 0644;
      pid /usr/pkg/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/pkg/etc/cust-rotation.conf;};log
   /usr/pkg/www/log/access_log{archivedir /depot/logs;
   date{minute 0;};index date;
   owner daemon;group staff;mode 0644;
   pid /usr/pkg/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/pkg/www/log/access_log {
      size 100k;
   };
   log /usr/pkg/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;
      index date;
      keep 100;
   };
   log /usr/pkg/www/log/access_log {
      date { minute 0; hour 0; };
      size 100k;
   };
   options {
      size 200k;
   };
   log /usr/pkg/www/log/error_log {
      date { minute 0; hour 0; };
   };

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/pkg/www/log/access_log {
      size;
   };
   log /usr/pkg/www/log/error_log {
      date {};
   };

FILES
/usr/pkg/etc/sarah.conf sarah configuration file

BUGS

•   A mode to force sarah to trim all logs is missing.

•   A testing mode is required where no log rotation is done, but verbose 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 $