[src/netbsd-1-5]: src/usr.bin/newsyslog Pull up revisions 1.13-1.21 (requeste...

[he <he%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/71ac04ed1261
branches:  netbsd-1-5
changeset: 492933:71ac04ed1261
user:      he <he%NetBSD.org@localhost>
date:      Wed Mar 06 23:35:03 2002 +0000

description:
Pull up revisions 1.13-1.21 (requested by martti):
  Synchronize to current development version.  This includes among
  other things the ``specific time for periodic trimming'' feature.

diffstat:

 usr.bin/newsyslog/newsyslog.8 |  314 +++++++++++++++++++++++++++++++++--------
 1 files changed, 252 insertions(+), 62 deletions(-)

diffs (truncated from 433 to 300 lines):

diff -r 355052fdc3f0 -r 71ac04ed1261 usr.bin/newsyslog/newsyslog.8
--- a/usr.bin/newsyslog/newsyslog.8     Wed Mar 06 23:34:45 2002 +0000
+++ b/usr.bin/newsyslog/newsyslog.8     Wed Mar 06 23:35:03 2002 +0000
@@ -1,11 +1,31 @@
-.\"    $NetBSD: newsyslog.8,v 1.12 1999/12/29 06:54:01 cgd Exp $
+.\"    $NetBSD: newsyslog.8,v 1.12.4.1 2002/03/06 23:35:03 he Exp $
+.\"
+.\" Copyright (c) 1999, 2000 Andrew Doran <ad%NetBSD.org@localhost>
+.\" 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.
 .\"
-.\" from FreeBSD: newsyslog.8,v 1.14.2.1 1999/02/25 18:38:33 wollman Exp
+.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
 .\"
-.\" 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
@@ -18,6 +38,8 @@
 .\" 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 November 20, 1999
 .Dt NEWSYSLOG 8
 .Os
@@ -26,14 +48,15 @@
 .Nd maintain system log files to manageable sizes
 .Sh SYNOPSIS
 .Nm newsyslog
-.Op Fl Fnrv
+.Op Fl nrsvF
 .Op Fl f Ar config_file
+.Op Pa file ...
 .Sh DESCRIPTION
-.Nm Newsyslog
+.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, 
+is determined to require archiving,
 .Nm
 rearranges the files so that
 .Dq Va logfile
@@ -45,15 +68,18 @@
 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.  
+space.
 .Pp
-A log can be archived for two reasons:
+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
@@ -64,19 +90,19 @@
 .Nm
 be run once hourly.
 .Pp
-When starting up, 
+When starting up,
 .Nm
 reads in a configuration file to determine which logs may potentially
 be archived.
-By default, this configuration file is 
+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 newsyslog .
-Each line has five mandatory fields and four optional fields, with a
+.Nm "" .
+Each line has six mandatory fields and three optional fields, with
 whitespace separating each field.  Blank lines or lines beginning with
 ``#'' are ignored.  The fields of the configuration file are as
-follows: 
+follows:
 .Pp
 .Bl -tag -width indent
 .It Ar logfile_name
@@ -87,14 +113,14 @@
 .Ar owner
 or
 .Ar group
-field is left blank.  The field may be numeric, or a name which is 
+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, "." is useable in lieu of ":", however use of
 this feature is discouraged.
-.It Ar mode 
+.It Ar mode
 Specify the mode of the log file and archives.
 .It Ar count
 Specify the number of archive files to be kept
@@ -107,36 +133,191 @@
 .Pq Ql \&* ,
 then the size of the log file is not taken into account
 when determining when to trim the log file.
-.It Ar interval
+.It Ar when
 The
-.Ar interval
-field specifies the time separation (in hours) between trimming of the 
-logfile.  If this field
-is replaced by an asterisk
-.Pq Ql \&* ,
-then the interval is not taken into account
-when determining when to trim the log file.
+.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:
+.Sm off
+.Oo
+.Va D\&hh
+.Oc ,
+.Oo
+.Va W\&w
+.Oo
+.Va D\&hh
+.Oc
+.Oc
+and
+.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 secifications 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