newsyslog(8)

NAME

newsyslog - maintain system log files to manageable sizes

SYNOPSIS

newsyslog  [-CFNnrsv]  [-R  tagname]  [-a   directory]   [-d
directory]
          [-f config_file] [file ...]

DESCRIPTION

The newsyslog utility should be scheduled to run periodical

ly by cron(8).
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
``logfile'' is empty, ``logfile.0'' has the last period's

logs in it,
``logfile.1'' has the next to last period's 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 can be archived for three reasons:

1. It is larger than the configured size (in kilo

bytes).

2. A configured number of hours have elapsed since

the log was
last archived.

3. This is the specific configured hour for rotation

of the log.

The granularity of newsyslog 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 hour without any ill effects, and mode three

(above) assumes
that this is so.

OPTIONS

The following options can be used with newsyslog:

-f config_file

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

-a directory
Specify a directory into which archived log files

will be written. If a relative path is given, it is appended to

the path of
each log file and the resulting path is used as the

directory
into which the archived log for that log file will

be written.
If an absolute path is given, all archived logs are

written into
the given directory. If any component of the path

directory does
not exist, it will be created when newsyslog is run.

-d directory
Specify a directory which all log files will be rel

ative to. To
allow archiving of logs outside the root, the

directory passed to
the -a option is unaffected.

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

-n Cause newsyslog not to trim the logs, but to print

out what it
would do if this option were not specified.

-r Remove the restriction that newsyslog must be run

ning as root.
Of course, newsyslog will not be able to send a HUP

signal to
syslogd(8) so this option should only be used in de

bugging.

-s Specify that newsyslog should not send any signals

to any daemon
processes that it would normally signal when rotat

ing a log file.
For any log file which is rotated, this option will

usually also
mean the rotated log file will not be compressed if

there is a
daemon which would have been signalled without this

option. However, this option is most likely to be useful when

specified with
the -R option, and in that case the compression will

be done.

-C If specified once, then newsyslog will create any

log files which
do not exist, and which have the C flag specified in

their config
file entry. If specified multiple times, then

newsyslog will
create all log files which do not already exist. If

log files
are given on the command-line, then the -C or -CC

will only apply
to those specific log files.

-F Force newsyslog to trim the logs, even if the trim

conditions
have not been met. This option is useful for diag

nosing system
problems by providing you with fresh logs that con

tain only the
problems.

-N Do not perform any rotations. This option is in

tended to be used
with the -C or -CC options when creating log files

is the only
objective.

-R tagname
Specify that newsyslog should rotate a given list of

files, even
if trim conditions are not met for those files. The

tagname is
only used in the messages written to the log files

which are
rotated. This differs from the -F option in that

one or more log
files must also be specified, so that newsyslog will

only operate
on those specific files. This option is mainly in

tended for the
daemons or programs which write some log files, and

want to trigger a rotate based on their own criteria. With this

option they
can execute newsyslog to trigger the rotate when

they want it to
happen, and still give the system administrator a

way to specify
the rules of rotation (such as how many backup

copies are kept,
and what kind of compression is done). When a dae

mon does execute newsyslog with the -R option, it should make

sure all of the
log files are closed before calling newsyslog, and

then it should
re-open the files after newsyslog returns. Usually

the calling
process will also want to specify the -s option, so

newsyslog
will not send a signal to the very process which

called it to
force the rotate. Skipping the signal step will al

so mean that
newsyslog will return faster, since newsyslog nor

mally waits a
few seconds after any signal that is sent.

If additional command line arguments are given, newsyslog

will only examine log files that match those arguments; otherwise, it will

examine all
files listed in the configuration file.

FILES

/etc/newsyslog.conf newsyslog configuration file

COMPATIBILITY

Previous versions of the newsyslog utility used the dot

(``.'') character
to distinguish the group name. Beginning with FreeBSD 3.3,

this has been
changed to a colon (``:'') character so that user and group

names may
contain the dot character. The dot (``.'') character is

still accepted
for backwards compatibility.

HISTORY

The newsyslog utility originated from NetBSD and first ap

peared in
FreeBSD 2.2.

AUTHORS

Theodore Ts'o, MIT Project Athena

Copyright 1987, Massachusetts Institute of Technology

SEE ALSO

bzip2(1), gzip(1), syslog(3), newsyslog.conf(5), chown(8),

syslogd(8)

BUGS

Does not yet automatically read the logs to find security

breaches.

BSD February 24, 2005

BSD