6a34ae85e9
config file. If the -C option is specified once, then newsyslog will create any entries which specify the 'C' option. If -C is given twice, then newsyslog will create all missing log files. Some of this code comes from NetBSD, although this implementation does not exactly match theirs. Reviewed by: freebsd-arch MFC after: 10 days
533 lines
14 KiB
Groff
533 lines
14 KiB
Groff
.\" This file contains changes from the Open Software Foundation.
|
|
.\"
|
|
.\" from: @(#)newsyslog.8
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software
|
|
.\" and its documentation for any purpose and without fee is
|
|
.\" hereby granted, provided that the above copyright notice
|
|
.\" appear in all copies and that both that copyright notice and
|
|
.\" this permission notice appear in supporting documentation,
|
|
.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
|
|
.\" used in advertising or publicity pertaining to distribution
|
|
.\" of the software without specific, written prior permission.
|
|
.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
|
|
.\" the suitability of this software for any purpose. It is
|
|
.\" provided "as is" without express or implied warranty.
|
|
.\"
|
|
.Dd April 27, 2003
|
|
.Dt NEWSYSLOG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm newsyslog
|
|
.Nd maintain system log files to manageable sizes
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl CFnrsv
|
|
.Op Fl R Ar tagname
|
|
.Op Fl a Ar directory
|
|
.Op Fl f Ar config_file
|
|
.Op Ar
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility should be scheduled to run periodically by
|
|
.Xr cron 8 .
|
|
When it is executed it archives log files if necessary. If a log file
|
|
is determined to require archiving,
|
|
.Nm
|
|
rearranges the files so that
|
|
.Dq Va logfile
|
|
is empty,
|
|
.Dq Va logfile Ns Li \&.0
|
|
has
|
|
the last period's logs in it,
|
|
.Dq Va logfile Ns Li \&.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.
|
|
.Pp
|
|
A log can be archived for three reasons:
|
|
.Bl -enum -offset indent
|
|
.It
|
|
It is larger than the configured size (in kilobytes).
|
|
.It
|
|
A configured number of hours have elapsed since the log was last
|
|
archived.
|
|
.It
|
|
This is the specific configured hour for rotation of the log.
|
|
.El
|
|
.Pp
|
|
The granularity of
|
|
.Nm
|
|
is dependent on how often it is scheduled to run by
|
|
.Xr 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.
|
|
.Pp
|
|
When starting up,
|
|
.Nm
|
|
reads in a configuration file to determine which logs may potentially
|
|
be archived.
|
|
By default, this configuration file is
|
|
.Pa /etc/newsyslog.conf .
|
|
Each line of the file contains information about a particular log file
|
|
that should be handled by
|
|
.Nm .
|
|
Each line has five mandatory fields and four optional fields, with
|
|
whitespace separating each field. Blank lines or lines beginning with
|
|
``#'' are ignored. If ``#'' is placed in the middle of the line,
|
|
``#'' character and the rest of the line after it is ignored.
|
|
To prevent special meaning, the ``#'' may be escaped with ``\\'',
|
|
in this case preceding ``\\'' is removed and ``#'' treated as ordinary
|
|
character. The fields of the configuration file are as
|
|
follows:
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Ar logfile_name
|
|
Name of the system log file to be archived, or the literal string
|
|
``<default>''.
|
|
The special default entry will be only be used if some log file
|
|
name is given as a command line argument on the
|
|
.Nm
|
|
command, and if that log file name is not matched by any other
|
|
line in the configuration file.
|
|
.It Ar owner : Ns Ar group
|
|
This optional field specifies the owner and group for the archive file.
|
|
The ":" is essential, even if the
|
|
.Ar owner
|
|
or
|
|
.Ar group
|
|
field is left blank. The field may be numeric, or a name which is
|
|
present in
|
|
.Pa /etc/passwd
|
|
or
|
|
.Pa /etc/group .
|
|
.It Ar mode
|
|
Specify the mode of the log file and archives.
|
|
.It Ar count
|
|
Specify the number of archive files to be kept
|
|
besides the log file itself.
|
|
.It Ar size
|
|
When the size of the log file reaches
|
|
.Ar size
|
|
in kilobytes,
|
|
the log file will be trimmed as described above. If this field
|
|
is replaced by an asterisk
|
|
.Pq Ql \&* ,
|
|
then the size of the log file is not taken into account
|
|
when determining when to trim the log file.
|
|
.It Ar when
|
|
The
|
|
.Ar when
|
|
field can consist of an interval, a specific time, or both. If
|
|
the
|
|
.Ar when
|
|
field is an asterisk
|
|
.Pq Ql \&*
|
|
log rotation will depend only on the contents of the
|
|
.Ar size
|
|
field.
|
|
Otherwise, the
|
|
.Ar when
|
|
field consists of an optional interval in hours, optionally followed
|
|
by an
|
|
.So Li \&@ Sc Ns No -sign
|
|
and a time in a restricted
|
|
.Tn ISO 8601
|
|
format or by an
|
|
.So Li \&$ Sc Ns No -sign
|
|
and a time specification for logfile rotation at a fixed time once
|
|
per day, per week or per month.
|
|
.Pp
|
|
If a time is specified, the log file will only be trimmed if
|
|
.Nm
|
|
is run within one hour of the specified time. If an
|
|
interval is specified, the log file will be trimmed if that many hours have
|
|
passed since the last rotation. When both a time and an interval are
|
|
specified, both conditions must be satisfied for the rotation to take
|
|
place.
|
|
.Pp
|
|
There is no provision for specification of a timezone. There is
|
|
little point in specifying an explicit minutes or seconds component in
|
|
the current implementation, since the only comparison is `within the
|
|
hour'.
|
|
.Pp
|
|
.Sy ISO 8601 restricted time format
|
|
.Pp
|
|
The lead-in character for a restricted
|
|
.Tn ISO 8601
|
|
time is
|
|
an
|
|
.So Li \&@ Sc Ns No -sign .
|
|
The particular format of the time in restricted
|
|
.Tn ISO 8601
|
|
is:
|
|
.Sm off
|
|
.Oo
|
|
.Oo
|
|
.Oo
|
|
.Oo
|
|
.Oo
|
|
.Va \&cc
|
|
.Oc
|
|
.Va \&yy
|
|
.Oc
|
|
.Va \&mm
|
|
.Oc
|
|
.Va \&dd
|
|
.Oc
|
|
.Oo
|
|
.Li \&T
|
|
.Oo
|
|
.Va \&hh
|
|
.Oo
|
|
.Va \&mm
|
|
.Oo
|
|
.Va \&ss
|
|
.Oc
|
|
.Oc
|
|
.Oc
|
|
.Oc
|
|
.Oc .
|
|
.Sm on
|
|
Optional date fields default to the appropriate component of the
|
|
current date; optional time fields default to midnight; hence if today
|
|
is January 22, 1999, the following date specifications are all
|
|
equivalent:
|
|
.Pp
|
|
.Bl -item -compact -offset indent
|
|
.It
|
|
.Sq Li 19990122T000000
|
|
.It
|
|
.Sq Li 990122T000000
|
|
.It
|
|
.Sq Li 0122T000000
|
|
.It
|
|
.Sq Li 22T000000
|
|
.It
|
|
.Sq Li T000000
|
|
.It
|
|
.Sq Li T0000
|
|
.It
|
|
.Sq Li T00
|
|
.It
|
|
.Sq Li 22T
|
|
.It
|
|
.Sq Li \&T
|
|
.It
|
|
.Sq Li \&
|
|
.El
|
|
.Pp
|
|
.Sy Day, week and month time format
|
|
.Pp
|
|
The lead-in character for day, week and month specification is a
|
|
.So Li \&$ Sc Ns No -sign .
|
|
The particular format of day, week and month specification is:
|
|
.Op Va D\&hh ,
|
|
.Op Va W\&w Ns Op Va D\&hh
|
|
and
|
|
.Op Va M\&dd Ns Op Va D\&hh
|
|
respectively.
|
|
Optional time fields default to midnight.
|
|
The ranges for day and hour specifications are:
|
|
.Pp
|
|
.Bl -tag -width Ds -compact -offset indent
|
|
.It Ar hh
|
|
hours, range 0 ... 23
|
|
.It Ar w
|
|
day of week, range 0 ... 6, 0 = Sunday
|
|
.It Ar dd
|
|
day of month, range 1 ... 31, or the letter
|
|
.Em L
|
|
or
|
|
.Em l
|
|
to specify the last day of the month.
|
|
.El
|
|
.Pp
|
|
Some examples:
|
|
.Pp
|
|
.Bl -tag -width Ds -compact -offset indent
|
|
.It Ar $D0
|
|
rotate every night at midnight
|
|
(same as
|
|
.Ar @T00 )
|
|
.It Ar $D23
|
|
rotate every day at 23:00 hr
|
|
(same as
|
|
.Ar @T23 )
|
|
.It Ar $W0D23
|
|
rotate every week on Sunday at 23:00 hr
|
|
.It Ar $W5D16
|
|
rotate every week on Friday at 16:00 hr
|
|
.It Ar $M1D0
|
|
rotate at the first day of every month at midnight
|
|
(i.e., the start of the day; same as
|
|
.Ar @01T00 )
|
|
.It Ar $M5D6
|
|
rotate on every 5th day of month at 6:00 hr
|
|
(same as
|
|
.Ar @05T06 )
|
|
.El
|
|
.Pp
|
|
.It Ar flags
|
|
This optional field is made up of one or more characters
|
|
that specify any special processing to be done for the log
|
|
files matched by this line.
|
|
The following are valid flags:
|
|
.Bl -tag -width indent
|
|
.It Sy B
|
|
indicates that the log file is a binary file, or has some
|
|
special format.
|
|
Usually
|
|
.Nm
|
|
inserts an
|
|
.Tn ASCII
|
|
message into a log file when rotating the file, to indicate
|
|
when and sometimes why the log file was rotated.
|
|
If
|
|
.Sy B
|
|
is specified, then that informational message will not be
|
|
inserted into the log file.
|
|
.It Sy C
|
|
indicates that the log file should be created if it does not
|
|
already exist, and if the
|
|
.Fl C
|
|
option was also specified on the command line.
|
|
.It Sy G
|
|
indicates that the specified
|
|
.Ar logfile_name
|
|
is a shell pattern, and that
|
|
.Nm
|
|
should archive all filenames matching that pattern, using the
|
|
other options specified on this line.
|
|
See
|
|
.Xr glob 3
|
|
for details on syntax and matching rules.
|
|
.It Sy J
|
|
indicates that
|
|
.Nm
|
|
should attempt to save disk space by compressing the rotated
|
|
log file using
|
|
.Xr bzip2 1 .
|
|
.It Sy N
|
|
indicates that there is no process which needs to be signalled
|
|
when this log file is rotated.
|
|
.It Sy U
|
|
indicates that the file specified by
|
|
.Ar path_to_pid_file
|
|
will contain the id for a process group, instead of a process.
|
|
This option also requires that the first line in that file must
|
|
be a negative value, to distinguish it from a value for a
|
|
process id.
|
|
.It Sy W
|
|
if used with the
|
|
.Sy Z
|
|
or
|
|
.Sy J
|
|
flag, this indicates that
|
|
.Nm
|
|
should wait for previously started compression jobs to complete before
|
|
starting a new one for this entry.
|
|
If this is used with the
|
|
.Sy G
|
|
flag, and if multiple log files match the given pattern, then
|
|
.Nm
|
|
will compress those logs one by one.
|
|
This ensures that only one compression job is running at a time.
|
|
.It Sy Z
|
|
indicates that
|
|
.Nm
|
|
should attempt to save disk space by compressing the rotated
|
|
log file using
|
|
.Xr gzip 1 .
|
|
.It Sy -
|
|
a minus sign will not cause any special processing, but it
|
|
can be used as a placeholder to create a
|
|
.Ar flags
|
|
field when you need to specify any of the following fields.
|
|
.El
|
|
.It Ar path_to_pid_file
|
|
This optional field specifies the file name to read to find the daemon
|
|
process id, or to find a process group id if the
|
|
.Sy U
|
|
flag was specified.
|
|
If this field is present, a
|
|
.Ar signal_number
|
|
is sent the process id contained in this file.
|
|
If this field is not present, then a SIGHUP signal will be
|
|
sent to
|
|
.Xr syslogd 8 ,
|
|
unless the
|
|
.Sy N
|
|
flag has been specified.
|
|
This field must start with "/" in order to be recognized
|
|
properly.
|
|
.It Ar signal_number
|
|
This optional field specifies the signal number that will be sent
|
|
to the daemon process (or to all processes in a process group, if
|
|
the
|
|
.Sy U
|
|
flag was specified).
|
|
If this field is not present, then a SIGHUP signal will be sent.
|
|
.El
|
|
.Sh OPTIONS
|
|
The following options can be used with
|
|
.Nm :
|
|
.Bl -tag -width indent
|
|
.It Fl f Ar config_file
|
|
Instruct
|
|
.Nm
|
|
to use
|
|
.Ar config_file
|
|
instead of
|
|
.Pa /etc/newsyslog.conf
|
|
for its configuration file.
|
|
.It Fl a Ar directory
|
|
Specify a
|
|
.Ar 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
|
|
.Ar directory .
|
|
If any component of the path
|
|
.Ar directory
|
|
does not exist,
|
|
it will be created when
|
|
.Nm
|
|
is run.
|
|
.It Fl v
|
|
Place
|
|
.Nm
|
|
in verbose mode. In this mode it will print out each log and its
|
|
reasons for either trimming that log or skipping it.
|
|
.It Fl n
|
|
Cause
|
|
.Nm
|
|
not to trim the logs, but to print out what it would do if this option
|
|
were not specified.
|
|
.It Fl r
|
|
Remove the restriction that
|
|
.Nm
|
|
must be running as root. Of course,
|
|
.Nm
|
|
will not be able to send a HUP signal to
|
|
.Xr syslogd 8
|
|
so this option should only be used in debugging.
|
|
.It Fl s
|
|
Specify that
|
|
.Nm
|
|
should not send any signals to any daemon processes that it would
|
|
normally signal when rotating 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
|
|
.Fl R
|
|
option, and in that case the compression will be done.
|
|
.It Fl C
|
|
If specified once, then
|
|
.Nm
|
|
will create any log files which do not exist, and which have the
|
|
.Sy C
|
|
flag specified in their config file entry.
|
|
If specified multiple times, then
|
|
.Nm
|
|
will create all log files which do not already exist.
|
|
If log files are given on the command-line, then the
|
|
.Fl C
|
|
or
|
|
.Fl CC
|
|
will only apply to those specific log files.
|
|
.It Fl F
|
|
Force
|
|
.Nm
|
|
to trim the logs, even if the trim conditions have not been met. This
|
|
option is useful for diagnosing system problems by providing you with
|
|
fresh logs that contain only the problems.
|
|
.It Fl R Ar tagname
|
|
Specify that
|
|
.Nm
|
|
should rotate a given list of files, even if trim conditions are not
|
|
met for those files.
|
|
The
|
|
.Ar tagname
|
|
is only used in the messages written to the log files which are
|
|
rotated.
|
|
This differs from the
|
|
.Fl F
|
|
option in that one or more log files must also be specified, so that
|
|
.Nm
|
|
will only operate on those specific files.
|
|
This option is mainly intended 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
|
|
.Nm
|
|
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 daemon does execute
|
|
.Nm
|
|
with the
|
|
.Fl R
|
|
option, it should make sure all of the log files are closed before
|
|
calling
|
|
.Nm ,
|
|
and then it should re-open the files after
|
|
.Nm
|
|
returns.
|
|
Usually the calling process will also want to specify the
|
|
.Fl s
|
|
option, so
|
|
.Nm
|
|
will not send a signal to the very process which called it to force
|
|
the rotate.
|
|
Skipping the signal step will also mean that
|
|
.Nm
|
|
will return faster, since
|
|
.Nm
|
|
normally waits a few seconds after any signal that is sent.
|
|
.El
|
|
.Pp
|
|
If additional command line arguments are given,
|
|
.Nm
|
|
will only examine log files that match those arguments; otherwise, it
|
|
will examine all files listed in the configuration file.
|
|
.Sh FILES
|
|
.Bl -tag -width /etc/newsyslog.confxxxx -compact
|
|
.It Pa /etc/newsyslog.conf
|
|
.Nm
|
|
configuration file
|
|
.El
|
|
.Sh BUGS
|
|
Doesn't yet automatically read the logs to find security breaches.
|
|
.Sh AUTHORS
|
|
.An Theodore Ts'o ,
|
|
MIT Project Athena
|
|
.Pp
|
|
Copyright 1987, Massachusetts Institute of Technology
|
|
.Sh COMPATIBILITY
|
|
Previous versions of the
|
|
.Nm
|
|
utility used the dot (``.'') character to
|
|
distinguish the group name.
|
|
Beginning with
|
|
.Fx 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.
|
|
.Sh "SEE ALSO"
|
|
.Xr gzip 1 ,
|
|
.Xr syslog 3 ,
|
|
.Xr chown 8 ,
|
|
.Xr syslogd 8
|