NAME

newsyslog - maintain system log files to manageable sizes

SYNOPSIS

newsyslog [-V] | -M | -i interval [-m |] [-T HH:MM] [-Fdnrv] [-f config_file] [-p syslogd_pidfile] [log_file ...]

DESCRIPTION

Newsyslog is a program that should be scheduled to run periodically by cron. When it is executed it archives log files if necessary. If a log file is determined to require archiving, newsyslog rearranges the files so that ``log_file'' is empty, ``log_file.0'' has the last period's logs in it, ``log_file.1'' has the next to last period's logs in it, and so on, up to a user-specified number of archived logs. The archived logs may also be compressed to save space. After all file operations are done newsyslog notifies the syslogd daemon, or optionally some log-file specific daemon, by sending a SIGHUP to the daemon process.

A log can be archived because of two reasons. The log file can have grown bigger than a preset size in kilobytes, or a preset number of hours may have elapsed since the last log archive. The granularity of newsyslog is dependent on how often it is scheduled to run by cron. Since the program is quite fast, it may be scheduled to run at least every ten minutes without any ill effects. However even more frequent runs may be necessary to catch extremely fast growing log files when files are trimmed by size, and newsyslog may be run as often as every minute without harm to facilitate this need.

When starting up, newsyslog reads in a configuration file to determine which logs should be looked at. By default, this configuration file is /etc/newsyslog.conf. Note that a POSIX advisory lock is obtained on the configuration file using the open(2) O_EXLOCK flag. This both prevents simultaneous execution of newsyslog using the same configuration file, as well as preventing the reading of the file while it is being modified by any text editor which uses the same locking feature (for example vi(1)).

If any log_file parameters are given then processing is restricted to just the specified files. The control specifications for the specified files are taken from the configuration file. Any files specified which do not correspond to entries in the configuration file will be ignored.

OPTIONS

The following options can be used with newsyslog:

-d
Place newsyslog into debug mode. No actions will be performed. If the -v option is also given then messages about what would be done will be printed without doing anything. Repeat -d to debug all archive rollovers even if they don't yet exist. Use of this option implies -r too.

-f config_file
Instruct newsyslog to use config_file instead of /etc/newsyslog.conf for its configuration file.

-F
Force newsyslog to trim log files immediately. Note that the -M and -m options are not ignored thus making it possible to force trimming of only interval controlled logs.

This option can be useful to initialize a freshly installed system with initial archive copies to ensure reliable interval calculation based on the age of the most recent archive file. This option can also be useful to mark an important system milestone in all logs newsyslog manages.

-i run_interval
Specify the interval, in minutes, between runs of newsyslog by cron. This option is necessary if the configuration file contains any interval field values which contain roll-over time specifications (i.e. time of day, week, or month). If you are running newsyslog by hand then just specify an interval of 1. The -i option is preferred over the -m and -M options as this is the only way time-of-day specifications as the trim interval are supported.

-m
Cause newsyslog to trim log files which have an interval specified as an even multiple of 24 hours as well as any which may have grown beyond their allowed size. I.e. do the ``midnight'' archiving of logs that must be archived at the same time every day or every N days. You probably only want to specify this option for one invocation per 24 hours and you probably want to use the corresponding -M flag on all other periodic invocations.

This option is deprecated and will be removed in the next major release.

-M
Prevent newsyslog from trimming log files which have an interval specified as an even multiple of 24 hours (i.e. the ones that would be archived when the -m option is given).

This option is deprecated and will be removed in the next major release.

-n
Cause newsyslog not to trim the logs, but to print on its standard output what it would do if this option were not specified. The result should be a shell script that would duplicate the actions of newsyslog were it to be run without the -n flag. Use of this option implies -r too.

-p syslogd_pidfile
Instruct newsyslog to use syslogd_pidfile instead of /var/run/syslogd.pid as the PID file for syslogd.

-r
Remove the restriction that newsyslog must be running as root. Of course, newsyslog will not be able to send a HUP signal to syslogd or most other daemons so this option is probably only useful for debugging unless an alternate configuration file is specified.

-s
Do not send any signals. This is useful if you wish to trim log files at boot time before any of the daemon processes to be signaled will be running. This options is primarily provided for compatibility with the native NetBSD version of newsyslog where it is used in the optional /etc/rc.d/newsyslog script.

-T HH:MM
Pretend the current time is HH:MM instead of the current time. The time given is always treated as a future time. This option is mostly useful for testing configurations.

-v
Place newsyslog in verbose mode. In this mode it will print out each log and its reasons for either trimming that log or skipping it.

FILES

/etc/newsyslog.conf
newsyslog configuration file.
/var/run/syslogd.pid
The default location of the PID for syslogd.

SEE ALSO

compress(1), cron(8), gzip(1), newsyslog.conf(5), syslog(3), syslogd(8) zgrep(1), zmore(1)

STANDARDS

None.

HISTORY

Originated at MIT Project Athena.

Someone at OSF hacked on it too.

A newsyslog command appeared in 4.4BSD.

There was an extremely simple shell script of similar purpose, /usr/lib/newsyslog, in SunOS-4.1.

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

Theodore Ts'o
, MIT Project Athena

Copyright 1987, Massachusetts Institute of Technology

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

BUGS

When the -m and -M options, or the -i option, are not in use, and when the time period is not evenly divisible by 24, log files that are archived based on a time period will not be rolled over at the same time of day. In fact the roll-over time will likely creep around the clock.

newsyslog sends SIGHUP to the associated daemon process for every log file trimmed. This is done to ensure that it's safe to compress the file after it has hopefully been closed. In theory we could try to optimize this procedure to only notify the daemon(s) once (and of course to batch all the compression commands at the end of the run). The current behaviour is normally harmless for syslogd and multiple signals can be avoided for other daemons by ensuring their PID files are only listed once with the last associated log file 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 requirer signalling every time any one of their logs are rolled over anyway, especially if their different logs have different roll-over policies.