Add support for rotating files at a specific time; from FreeBSD

1 files changed, 164 insertions, 29 deletions

diff --git a/usr.bin/newsyslog/newsyslog.8 b/usr.bin/newsyslog/newsyslog.8
index ec02d73a517..4e01c911d42 100644
--- a/usr.bin/newsyslog/newsyslog.8
+++ b/usr.bin/newsyslog/newsyslog.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: newsyslog.8,v 1.32 2003/02/09 07:26:45 jmc Exp $
+.\"	$OpenBSD: newsyslog.8,v 1.33 2003/02/12 19:17:36 millert Exp $
 .\"
 .\" Copyright (c) 1997, Jason Downs.  All rights reserved.
 .\"
@@ -77,7 +77,7 @@ the last period's logs in it,
 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.
+The archived logs may be optionally compressed to save space.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
@@ -116,7 +116,9 @@ signal to
 .Xr syslogd 8 ,
 so this option should only be used in debugging.
 .It Fl v
-Be verbose.
+Place
+.Nm newsyslog
+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 a Ar directory
@@ -180,12 +182,12 @@ are ignored.
 The fields of the configuration file are as
 follows:
 .Bl -tag -width XXXXXXXXXXXXXXXX
-.It logfile name
+.It Ar logfile_name
 The full pathname of the system log file to be archived.
-.It owner.group of archives (optional)
-Specify an ownership and group for the archive file.
+.It Ar owner:group
+This optional field specifies the owner and group for the archive file.
 The
-.Ql \&.
+.Ql :
 is essential, even if the
 .Ar owner
 or
@@ -193,15 +195,19 @@ or
 field is left blank.
 The fields may be numeric, or a name which is looked up
 in the system password and group databases.
-.It mode of logfile & archives
-Octal mode of created log files and archives.
-.It number of archives
-Specify the number of archives to be kept besides the log file itself.
-.It size of archives
+For backwards compatibility, a
+.Ql \&.
+may be used instead of a
+.Ql : .
+.It Ar mode
+File mode (in octal) to use for created log files and archives.
+.It Ar count
+The number of archives to be kept besides the log file itself.
+.It Ar size
 When the size of the log file (in kilobytes) reaches this point, the log
 file is trimmed as described above.
-If this field is replaced by a
-.Ql * ,
+If this field is replaced by an
+.Ql \&* ,
 then the size of
 the log file is not taken into account when determining when to trim the
 log file.
@@ -212,14 +218,138 @@ This prevents
 .Nm
 from rotating files consisting solely of a message indicating
 that the log file has been turned over.
-.It archive interval
-Specify the time separation between the trimming of the log file.
-If this field is replaced by a
-.Ql * ,
-the number of hours since the last time the
-log was trimmed will not be taken into consideration.
-.It flags (optional)
+.It Ar when
 The
+.Ar when
+field can consist of an interval, a specific time, or both.
+If the
+.Ar when
+field consists of 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, possibly followed
+by an
+.So Li \&@ Sc Ns No -sign
+and a time in a restricted
+.Tn ISO 8601
+format or by a
+.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 the 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
+.Sq within the hour .
+.Ss ISO 8601 restricted time format
+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
+For example, if today is January 22, 1999, the following date specifications
+are all equivalent:
+.Pp
+.Bl -item -compact -offset indent
+.It
+.Ql 19990122T000000
+.It
+.Ql 990122T000000
+.It
+.Ql 0122T000000
+.It
+.Ql 22T000000
+.It
+.Ql T000000
+.It
+.Ql T0000
+.It
+.Ql T00
+.It
+.Ql 22T
+.It
+.Ql \&T
+.It
+.Ql \&
+.El
+.Ss Day, week and month time format
+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
+.Ss Some examples:
+.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 on 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 the month at 6:00 hr
+(same as
+.Ar @05T06 )
+.El
+.Pp
+.It Ar flags
+The optional
 .Ar flags
 field specifies if the archives should have any special processing
 done to the archived log files.
@@ -245,19 +375,23 @@ log file.
 The
 .Sq F
 flag specifies that symbolic links should be followed.
-.It monitor notification (only used with the `M' flag)
+.It Ar monitor
 Specify the username (or email address) that should receive notification
 messages if this is a monitored log file.
 Notification messages are sent as email; the operator
 deserves what they get if they mark the
 .Xr sendmail 8
 log file as monitored.
-.It pid file (optional)
-Specify a file containing the PID of a process to send a
-.Dv SIGHUP
-signal to instead of
+This field is only valid when the
+.Sq M
+flag is set.
+.It Ar pid_file
+This optional field specifies a file containing the PID of a process to send a
+signal (usually
+.Dv SIGHUP )
+to instead of
 .Pa /var/run/syslog.pid .
-.It signal (optional)
+.It Ar signal
 Specify the signal to send to the process instead of
 .Dv SIGHUP .
 Signal names
@@ -265,8 +399,9 @@ must start with
 .Dq SIG
 and be the signal name, not the number, e.g.,
 .Dv SIGUSR1 .
-.It command (optional)
-Specify a command to run instead of sending a signal to the process.
+.It Ar command
+This optional field specifies a command to run instead of sending a signal
+to the process.
 The command must be enclosed in double quotes
 .Pq Ql \&" .
 The empty string,