Add a newsyslog.conf manual page. This follows suit with the other utilities
which have configuration files. This is just a cut-paste from newsyslog.8 with the following changes: o Kill hard sentence breaks. o Markup fixes. o Wordsmithing.
This commit is contained in:
Tom Rhodes
parent
ef4b3aa2e3
commit
0e9628026f
@ -35,6 +35,7 @@ MAN= acct.5 \
|
||||
motd.5 \
|
||||
msdosfs.5 \
|
||||
networks.5 \
|
||||
newsyslog.conf.5 \
|
||||
nsmb.conf.5 \
|
||||
nsswitch.conf.5 \
|
||||
passwd.5 \
|
||||
|
||||
370
share/man/man5/newsyslog.conf.5
Normal file
370
share/man/man5/newsyslog.conf.5
Normal file
@ -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 .
|
||||
Loading…
Reference in New Issue
Block a user