NAME

DESCRIPTION

logfile_name

Name of the system log file to be archived.

owner:group

This optional field specifies the owner and group for the archive file. The colon-separated subfields may be numeric, or a name which is present in /etc/passwd or /etc/group respectively. Either of the file's user-id or group-id may be left unchanged from the ownership of the current file by specifying it as ``-1.''

mode

Specifies the file permissions of the log file and its archival copies in the standard three-digit octal format.

count

Specify the number of archive files to be kept besides the log file itself.

size

When the size of the log file reaches the number of kilobytes specified by size, the log file will be trimmed as described above. If this field is replaced by a *, then the size of the log file is not taken into account when determining when to trim the log file.

when

The when field can consist of an interval, a specific time, or both. If the when field is an asterisk (`*') log rotation will depend only on the contents of the size field.

In the simple form of digits only they are interpreted as number of hours. When interval hours have passed, the log file will be trimmed. Note that if this value is an even multiple of 24 hours it may have special meaning depending on the way newsyslog is invoked (see the description of the -m and -M options in the newsyslog(8) manual page). Note also that when the -m and -M options are not used, and when the interval is not evenly divisible by 24, log files will not be rolled over at the same time of day. In fact the roll-over time will probably creep around the clock, unless it is followed by a time specification.

A time specification to fix the log file's rotation at a specified time, once per day, per week, or per month may also be given. If it follows an interval then it must be separated by a hyphen (i.e. a minus sign, `-').

WARNING: When a time specification is given for any log file newsyslog must be invoked with the -i option to tell it at what interval it is being run so that it can approximate the time of day calculations. Note that one full minute is subtracted from the interval to give the time range after which the specification remains valid. For example if an interval of 15 minutes is specified then a time specification will match if the current time is within 14 minutes after the specified time.

The daily, weekly, and/or monthly specification is given as: [Dhh,] [Dhh ] [Ww] and [Dhh ] [Mdd] respectively (with letters in either uppercase or lowercase). The time-of-day fields, which are optional, default to midnight. The ranges and meanings for these specifications are:

hh

hours, range 0 ... 23

w

day of week, range 0 ... 6, 0 = Sunday

dd

day of month, range 1 ... 31, or the letter L or l to specify the last day of the month.

Some examples:

D0

rotate every night at midnight

D23

rotate every day at 23:00 hr

W0D23

rotate every week on Sunday at 23:00 hr

W5

rotate every week on Friday at midnight.

MLD6

rotate at the last day of every month at 6:00 hr

M5

rotate on every 5th day of month at midnight

If an interval and a time specification are both given, then both conditions must be met. I.e. the file must be as old or older than the specified interval, and the current time must match the time specification. This means that it is most useful to specify just an hour of the day (e.g. D6, for 6:00 hr) and an interval which is an even multiple of 24 hours.

Normally the age of the log file will be determined by looking at the last modification time of the most recent archive copy, if one exists. If there is no archive copy, and the file is not marked as binary (see the B flag below), then newsyslog will make a somewhat feeble attempt to read the time-stamp from the first entry in the current log file (see the source for possible formats).

The log file age has 30 minutes added to it in order to ensure that at a regular interval (especially 24hr multiple) the file is likely to to appear old enough to roll over. This is mostly necessary for when the archive copy may not exist and the initial entry may not have been made right after log file roll-over.

flags

This optional field specifies if the archive should have any special processing done to the archived log files.

b

The b flag means that the file is a binary file, and so the ASCII message which newsyslog.conf inserts to indicate the fact that the logs have been turned over should not be included.

C

The C flag forces the creation of the new empty log file. This is the opposite of the D flag and will re-enable file creation if it appears later in the field. This flag is for backward compatability with the native NetBSD version of newsyslog.

D

The D flag prevents the creation of the new empty log file. This may be useful to avoid cluttering log directories with files that'll never be used, or when a daemon creates its own log file(s) on demand (failure to use this flag in the latter case may result in spurious warnings should newsyslog and the daemon both try to create the log file). Note though this flag should not be used with daemons like syslogd which require the log file to exist prior to when they start and prior to when they're signalled to re-open their log file(s).

N

The N flag prevents newsyslog from sending any signal to any process when the associated file is rolled over. This is the equivalent of specifying ``/dev/null'' in the path_to_pid_file field.

Z

The Z flag will make the archive files compress to save space by using compress or gzip, depending on which was selected at compile time.

/

The / flag causes newsyslog to create and use a sub-directory for the archived logs by appending ``.old'' to the log file name. The names of the archived logs will simply be their generation numbers.

0

The 0 flag means that the most recent archive of the log file (i.e. the one that ends in ``.0'') should not be compressed even when the Z flag is given. (This flag may also be specified as P for compatability with NetBSD.) This flag is necessary when managing log files written directly to by long-running processes (e.g. smail, httpd, etc.). This flag also makes it more convenient to browse through the most recently archived log file without having to first uncompress it or use tools like zmore, or zgrep, etc.

-

The - flag means nothing, but may be used as a place-holder when either or both of the path_to_pid_file and sigtype fields are specified for entries without any flags.

Flags may be specified in either uppercase or lowercase.

path_to_pid_file

This optional field specifies the file name from which to read the associated daemon's process-ID. If this field is present, and is not ``/dev/null'', a SIGHUP is sent the process-ID contained in this file. If this field is not present then the process-ID found in the default file (the one given by the parameter of the -p flag on the newsyslog command line, or by default /var/run/syslogd.pid).

This field must start with a slash (i.e. ``/'') in order to be recognised properly.

sigtype

This optional field specifies the type of signal to be sent to the daemon process. This may be a numeric or symbolic value. By default a SIGHUP (hang-up) will be sent if this field is left blank.

EXAMPLE

A configuration file might appear as follows:

#
#       newsyslog.conf - sample configuration file for newsyslog
#
# WARNING:  the values used in this sample file are strictly for
# demonstration and documentation purposes and are not necessarily the
# best for real life use!
#
#ident "#(@):newsyslog-1_1_0_81:newsyslog.conf,v 1.15 2009/03/04 19:38:04 woods Exp"
#
# log_filename  [owner:group] mode count kb   hrs/at [flgs][/pid_file][sig]
#               |             |    |     |    |      |     |          |
/var/log/aculog uucp:dialer   640  10    *    ML     DZ/0  /dev/null  SIGINT
/var/log/auth                 640  10    100  *      Z/0              sighup
/var/log/authpriv             640  10    100  *      Z/0
/var/log/cron                 640  3     *    D0     Z/0              HUP
/var/log/daemon               644  8     500  168    Z/0              hup
/var/log/debug                640  4     1000 168    Z/0
/var/log/httpd/access_log     644  5     *  D0 Z/0 /var/run/httpd.pid USR1
/var/log/httpd/error_log      644  5     *  D0 Z/0 /var/run/httpd.pid USR1
/var/log/important            644  6     *    W0     Z/0
/var/log/kerberos.log         640  10    *    D0     bDNZ/0
/var/log/kern                 644  10    500  *      Z/0
/var/log/local                644  10    1000 168    Z/0
/var/log/lpd-errs daemon:staff 644 4     100  *      Z/0
/var/log/lpr                  644  5     250  *      Z/0
/var/log/mail  root:staff     640  52    *    W0     Z/0
/var/log/messages             644  10    500  168    Z/
/var/log/news  news:news      644  2     *    D0     Z/0
/var/log/smail/logfile        644  52    *    W0     bDNZ/0
/var/log/smail/paniclog       644  5     500  168-D0 bDNZ/0
/var/log/syslog               640  3     500  *      Z/0
/var/log/user                 644  10    500  *      Z/0
/var/log/uucp  uucp:operator  644  5     *    W0     Z/0
/var/log/wtmp                 644  10    *    ML     bZ/0
/var/log/xferlog              640  10    *    W0     Z/0
/var/spool/uucp/Debug uucp:daemon 600 4  100  *      bDNZ/0
/var/spool/uucp/Log   uucp:daemon 644 10 *    W0     bDNZ/0

FILES

/etc/newsyslog.conf

The newsyslog configuration file.

/var/run/syslogd.pid

The default location of the PID for syslogd.

SEE ALSO

STANDARDS

COMPATABILITY

The FreeBSD version (and more recently the NetBSD version) allows a restricted form of an ISO 8601 time format to specify the time of day when a log file should be rotated. In those versions such a specification was given by placing it after an @`.blm Pp-sign ' following the [optional] interval. This version does not support that feature.

This version only allows the sufficiently useful daily, weekly, and/or monthly time specification with optional hour of day (also innovated by FreeBSD), and this version prefers to use the hyphen (-) as a separator from the optional interval instead of the far more confusing $`.blm Pp-sign. ' However the latter is permitted to allow for backwards compatability.

HISTORY

A newsyslog.conf file appeared in 4.4BSD.

The path_to_pid_file optional field was added by FreeBSD.

The sigtype optional field was added by NetBSD.

The optional daily, weekly, and/or monthly time specification feature was added by FreeBSD.

This particular version's feature set, and this separate manual page for the configuration file, was put together by Greg A. Woods
, Planix, Inc.

AUTHOR

Copyright 1987, Massachusetts Institute of Technology

This version by Greg A. Woods
, Planix, Inc.

BUGS

Fields such as interval and size should allow the units of measurement to be specified.

There is no provision for specification of a timezone in the interval field.

Listing the same path_to_pid_file multiple times will cause SIGHUP to be sent to the associated daemon process for every log file with the same PID file which is rolled over. This is done to ensure that it's safe to compress the file after it has hopefully been closed but in theory should be optimised to only notify daemon(s) once (and of course to batch all the compression commands to the end of the process). This behaviour is normally harmless for syslogd and multiple signals may be avoided for other daemons by ensuring their PID files are only listed once and that the 0 flag is used to ensure the most recent log file is not immediately compressed. Note that daemons which have multiple log files open may require signalling every time any one of their logs are rolled over anyway, especially if their different logs have different roll-over policies.

The age of the log file may be impossible to determine, especially for binary format files, if the most recent archive copy (logfile.0*) does not exist.

Anyone messing with the modification time of the most recent archive copy will possibly break the file age determination algorithm and thus mess up regular archive intervals for such files.