417 lines
10 KiB
Groff
417 lines
10 KiB
Groff
.\" $NetBSD: newsyslog.8,v 1.39 2013/12/20 17:01:39 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999, 2000 Andrew Doran <ad@NetBSD.org>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" This file contains changes from the Open Software Foundation.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" from FreeBSD: newsyslog.8,v 1.14.2.1 1999/02/25 18:38:33 wollman Exp
|
|
.\"
|
|
.Dd June 16, 2012
|
|
.Dt NEWSYSLOG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm newsyslog
|
|
.Nd maintain system log files to manageable sizes
|
|
.Sh SYNOPSIS
|
|
.Nm newsyslog
|
|
.Op Fl nrsvF
|
|
.Op Fl f Ar config_file
|
|
.Op Pa file ...
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a program that 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
|
|
The configured time for rotation of the log occurred within the last 60
|
|
minutes.
|
|
.El
|
|
.Pp
|
|
The granularity of
|
|
.Nm
|
|
is dependent on how often it is scheduled to run by
|
|
.Xr cron 8 .
|
|
It is recommended that
|
|
.Nm
|
|
be run once hourly.
|
|
.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 six mandatory fields and three optional fields, with
|
|
whitespace separating each field.
|
|
Blank lines or lines beginning with
|
|
.Dq #
|
|
are ignored.
|
|
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.
|
|
.It Ar owner:group
|
|
This optional field specifies the owner and group for the archive file.
|
|
The
|
|
.Dq \&:
|
|
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 .
|
|
For backward compatibility,
|
|
.Dq \&\.
|
|
is usable in lieu of
|
|
.Dq \&: ,
|
|
however use of this feature is discouraged.
|
|
.It Ar mode
|
|
Specify the mode of the log file and archives.
|
|
.It Ar ngen
|
|
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
|
|
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, the log will be trimmed if either condition is met.
|
|
.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
|
|
.Em 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
|
|
.Em 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:
|
|
.Oo
|
|
.Va D\&hh
|
|
.Oc ,
|
|
.Sm off
|
|
.Oo
|
|
.Va W\&w
|
|
.Oo
|
|
.Va D\&hh
|
|
.Oc
|
|
.Oc
|
|
.Sm on
|
|
and
|
|
.Sm off
|
|
.Oo
|
|
.Va M\&dd
|
|
.Oo
|
|
.Va D\&hh
|
|
.Oc
|
|
.Oc
|
|
.Sm on
|
|
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
|
|
.It Ar $D23
|
|
rotate every day at 23:00 hr
|
|
.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 $MLD0
|
|
rotate at the last day of every month at midnight
|
|
.It Ar $M5D6
|
|
rotate on every 5th day of month at 6:00 hr
|
|
.El
|
|
.Pp
|
|
.It Ar flags
|
|
This field specifies any special processing that is required.
|
|
These flags are parsed in a case insensitive manner.
|
|
Individual
|
|
flags and their meanings:
|
|
.Bl -tag -width indent
|
|
.It Sy -
|
|
This flag means nothing - it is used as a spacer when no flags are set.
|
|
.It Sy b
|
|
The file is a binary file or is not in
|
|
.Xr syslogd 8
|
|
format:
|
|
the
|
|
.Tn ASCII
|
|
message which
|
|
.Nm
|
|
inserts to indicate that the logs have been trimmed should not be included.
|
|
.It Sy c
|
|
Create an empty log file if none currently exists.
|
|
.It Sy n
|
|
No signal should be sent when the log is trimmed.
|
|
.It Sy p
|
|
The first historical log file (i.e. the historical log file with the suffix
|
|
.Dq \.0 )
|
|
should not be compressed.
|
|
.It Sy j
|
|
Archived log files should be compressed with
|
|
.Xr bzip2 1
|
|
to save space.
|
|
.It Sy x
|
|
Archived log files should be compressed with
|
|
.Xr xz 1
|
|
to save space.
|
|
.It Sy z
|
|
Archived log files should be compressed with
|
|
.Xr gzip 1
|
|
to save space.
|
|
.El
|
|
.It Ar path_to_pid_file
|
|
This optional field specifies
|
|
the file name to read to find the daemon process id.
|
|
If this field is missing, it defaults to the
|
|
.Pa /var/run/syslogd.pid
|
|
file.
|
|
A signal of type
|
|
.Ar sigtype
|
|
is sent to the process id contained in this
|
|
.Ar path_to_pid_file
|
|
file.
|
|
This field must start with
|
|
.Sq /
|
|
in order to be recognized properly.
|
|
.It Ar 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.
|
|
.El
|
|
.Sh OPTIONS
|
|
The following options can be used with newsyslog:
|
|
.Bl -tag -width indent
|
|
.It Fl f Ar config_file
|
|
Use
|
|
.Ar config_file
|
|
instead of
|
|
.Pa /etc/newsyslog.conf
|
|
as the configuration file.
|
|
.It Fl n
|
|
Do not trim the logs, but print out what would be done if this option were not
|
|
specified:
|
|
.Fl n
|
|
implies
|
|
.Fl v .
|
|
.It Fl r
|
|
Remove the restriction that
|
|
.Nm
|
|
must be running as root.
|
|
When running as a regular user,
|
|
.Nm
|
|
will not be able to send a HUP signal to
|
|
.Xr syslogd 8 ,
|
|
so this option should be used only when debugging or trimming user generated
|
|
logs.
|
|
.It Fl s
|
|
Do not signal daemon processes.
|
|
.It Fl v
|
|
Run in verbose mode.
|
|
In this mode each action that is taken will be printed.
|
|
.It Fl F
|
|
Force trimming of 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.
|
|
.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 SEE ALSO
|
|
.Xr bzip2 1 ,
|
|
.Xr gzip 1 ,
|
|
.Xr syslog 3 ,
|
|
.Xr syslogd 8
|