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.

interval

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 (eg. 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.

D

The D flag prevents the creation of the new empty log file. This can be useful to avoid cluttering log directories with files that'll never be used (though this flag should probably be avoided with daemons like syslogd which require the log file to exist prior to when they start); or when the owner of the file writes any special start records to a new log file that it creates.

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.

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.

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 (eg. 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 can 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 can 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 not ``/dev/null'', a SIGHUP is sent the process id contained in this file. 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:

#
# sample configuration file for newsyslog
#
# log_filename  [owner:group] mode count kb   hrs/at [flgs][/pid_file][sig]
#               |             |    |     |    |      |     |
/var/log/aculog uucp:dialer   640  10    *    ML     Z0    /dev/null  sigint
/var/log/auth                 640  10    100  *      Z0
/var/log/authpriv             640  10    100  *      Z0
/var/log/cron                 640  3     *    D0     Z0               HUP
/var/log/daemon               644  4     500  168    Z0               hup
/var/log/debug                640  4     1000 168    Z0
/var/log/httpd/access_log     644  5     *    D0     Z0    # only last one
/var/log/httpd/error_log      644  5     *   D0 Z0 /var/run/httpd.pid SIGUSR1
/var/log/kerberos.log         640  10    *    D0     Z0    /dev/null
/var/log/kern                 644  10    500  *      Z0
/var/log/local                644  10    1000 168    Z0
/var/log/lpd-errs daemon:staff 644 4     100  *      Z0
/var/log/lpd-acct daemon:staff 644 4     *    ML     Z0
/var/log/lpr                  644  5     250  *      Z0
/var/log/mail  root:staff     640  52    *    W0D0   Z0
/var/log/messages             644  10    1000 168    Z0
/var/log/news  news:news      644  2     *    D0     Z0
/var/log/smail/logfile        644  5     *    W0D0   Z0    /dev/null
/var/log/smail/paniclog       644  5     500  168-D0 Z0    /dev/null
/var/log/syslog               640  3     500  *      Z0
/var/log/user                 644  10    500  *      Z0
/var/log/uucp  uucp:operator  644  5     *    W0D0   Z0
/var/log/wtmp                 644  10    *    ML     BZ0
/var/log/xferlog              640  10    *    W0D0   Z0

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 version (and more recently the FreeBSDNetBSD 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 @`. -sign ' following the [optional] interval. This version only allows the sufficiently useful daily, weekly, and/or monthly time specification (also innovated by but it uses the hyphen (-) as a separator from the optional interval instead of the more confusing FreeBSD),$`


 -sign. '

HISTORY

A newsyslog.conf file appeared in 4.4BSD.

The path_to_pid_file optional field was added by

The FreeBSD.sigtype optional field was added by NetBSD.

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

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

AUTHOR

Copyright 1987, Massachusetts Institute of Technology

This version by Planix, Inc.

BUGS

Fields such as FreeBSD.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 can 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.

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.