From 4b582ba95577caf79b7539b898997ec12b49a6b0 Mon Sep 17 00:00:00 2001 From: trhodes Date: Fri, 12 Mar 2004 16:03:26 +0000 Subject: Move newsyslog.conf.5 to usr.sbin/newsyslog. There is no real history other than 'initial revision' thus I did not request a repocopy. Requested by: ru, gad --- usr.sbin/newsyslog/Makefile | 2 +- usr.sbin/newsyslog/newsyslog.conf.5 | 370 ++++++++++++++++++++++++++++++++++++ 2 files changed, 371 insertions(+), 1 deletion(-) create mode 100644 usr.sbin/newsyslog/newsyslog.conf.5 (limited to 'usr.sbin') diff --git a/usr.sbin/newsyslog/Makefile b/usr.sbin/newsyslog/Makefile index 61c2b08..9c301a1 100644 --- a/usr.sbin/newsyslog/Makefile +++ b/usr.sbin/newsyslog/Makefile @@ -1,7 +1,7 @@ # $FreeBSD$ PROG= newsyslog -MAN= newsyslog.8 +MAN= newsyslog.8 newsyslog.conf.5 SRCS= newsyslog.c ptimes.c WARNS?= 2 diff --git a/usr.sbin/newsyslog/newsyslog.conf.5 b/usr.sbin/newsyslog/newsyslog.conf.5 new file mode 100644 index 0000000..f86e77f --- /dev/null +++ b/usr.sbin/newsyslog/newsyslog.conf.5 @@ -0,0 +1,370 @@ +.\" This file was split from the newsyslog(8) manual page by Tom Rhodes +.\" and includes modifications as appropriate. +.\" The original header is included below: +.\" +.\" 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 March 10, 2004 +.Dt NEWSYSLOG.CONF 5 +.Os +.Sh NAME +.Nm newsyslog.conf +.Nd configuration of the newsyslog utility +.Sh DESCRIPTION +The +.Nm +file is used to set log file rotation configuration for the +.Xr newsyslog 8 +utility. +Configuration may designate that logs are rotated based on +size, last rotation time, or time of day. +The +.Nm +file can also be used to designate secure permissions to log +files at rotation time. +During initialization, +.Xr newsyslog 8 +reads a configuration file, +normally +.Pa /etc/newsyslog.conf , +to determine which logs may potentially be rotated and archived. +Each line has five mandatory fields and four optional fields +separated with whitespace. +Blank lines or lines beginning with +.Dq # +are ignored. +If +.Dq # +is placed in the middle of the line, the +.Dq # +character and the rest of the line after it is ignored. +To prevent special meaning, the +.Dq # +character may be escaped with +.Dq \e\e , +in this case preceding +.Dq \e\e +is removed and +.Dq # +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 +.Dq Aq default . +The special default entry will only be used if a log file +name is given as a command line argument to +.Xr newsyslog 8 , +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 +.Dq \&: +is essential regardless if the +.Ar owner +or +.Ar group +field is left blank or contains a value. +The field may be numeric, or a name which is present in +.Pa /etc/passwd +or +.Pa /etc/group . +.It Ar mode +Specify the file mode of the log file and archives. +.It Ar count +Specify the maximum number of archive files which may exist. +This does not consider the current log file. +.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 contains an asterisk +.Pq Ql \&* , +the log file will not be trimmed based on size. +.It Ar when +The +.Ar when +field may consist of an interval, a specific time, or both. +If the +.Ar when +field contains an asterisk +.Pq Ql \&* +log rotation will solely depend on the contents of the +.Ar size +field. +Otherwise, the +.Ar when +field consists of an optional interval in hours, usually followed +by an +.So Li \&@ Sc Ns No -sign +and a time in restricted +.Tn ISO 8601 +format. +Additionally, the format may also be constructed with a +.So Li \&$ Sc Ns No -sign +along with a rotation time specification of once +a day, once a week or once a month. +.Pp +If a time is specified, the log file will only be trimmed if +.Xr newsyslog 8 +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 then 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 . +.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 an +.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 one of the letters +.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 +.Xr newsyslog 8 +inserts an +.Tn ASCII +message into a log file during rotation. +This message is used 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 +.Xr newsyslog 8 +should archive all filenames matching that pattern using the +other options on this line. +See +.Xr glob 3 +for details on syntax and matching rules. +.It Sy J +indicates that +.Xr newsyslog 8 +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 signaled +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 +be a negative value to distinguish it from a process id. +.It Sy W +if used with the +.Sy Z +or +.Sy J +flag, this indicates that +.Xr newsyslog 8 +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 +.Xr newsyslog 8 +will compress those logs one by one. +This ensures that only one compression job is running at a time. +.It Sy Z +indicates that +.Xr newsyslog 8 +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 containing a daemon's +process id or to find a group process 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 +.Dv SIGHUP +signal will be sent to +.Xr syslogd 8 , +unless the +.Sy N +flag has been specified. +This field must start with +.Dq / +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 +.Dv SIGHUP +signal will be sent. +.El +.Sh SEE ALSO +.Xr bzip 1 , +.Xr gzip 1 , +.Xr syslog 3 , +.Xr chown 8 , +.Xr newsyslog 8 , +.Xr syslog 8 +.Sh HISTORY +This manual page first appeared in +.Fx 4.10 . -- cgit v1.1