fix mandoc(1) warnings in usr.sbin/
[dragonfly.git] / usr.sbin / newsyslog / newsyslog.conf.5
CommitLineData
521a7b05
SW
1.\" This file was split from the newsyslog(8) manual page by Tom Rhodes
2.\" and includes modifications as appropriate.
3.\" The original header is included below:
4.\"
5.\" This file contains changes from the Open Software Foundation.
6.\"
7.\" from: @(#)newsyslog.8
2d012f91 8.\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.conf.5,v 1.12 2011/01/31 11:30:26 mm Exp $
521a7b05
SW
9.\"
10.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
11.\"
12.\" Permission to use, copy, modify, and distribute this software
13.\" and its documentation for any purpose and without fee is
14.\" hereby granted, provided that the above copyright notice
15.\" appear in all copies and that both that copyright notice and
16.\" this permission notice appear in supporting documentation,
17.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
18.\" used in advertising or publicity pertaining to distribution
19.\" of the software without specific, written prior permission.
20.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
21.\" the suitability of this software for any purpose. It is
22.\" provided "as is" without express or implied warranty.
23.\"
2d012f91 24.Dd January 31, 2011
521a7b05
SW
25.Dt NEWSYSLOG.CONF 5
26.Os
27.Sh NAME
28.Nm newsyslog.conf
29.Nd
30.Xr newsyslog 8
31configuration file
32.Sh DESCRIPTION
33The
34.Nm
35file is used to set log file rotation configuration for the
36.Xr newsyslog 8
37utility.
38Configuration may designate that logs are rotated based on
39size, last rotation time, or time of day.
40The
41.Nm
42file can also be used to designate secure permissions to log
43files at rotation time.
44During initialization,
45.Xr newsyslog 8
46reads a configuration file,
47normally
48.Pa /etc/newsyslog.conf ,
49to determine which logs may potentially be rotated and archived.
50Each line has five mandatory fields and four optional fields,
51separated with whitespace.
52Blank lines or lines beginning with
53.Ql #
54are ignored.
55If
56.Ql #
57is placed in the middle of the line, the
58.Ql #
59character and the rest of the line after it is ignored.
60To prevent special meaning, the
61.Ql #
62character may be escaped with
51f35c5c 63.Ql \e ;
521a7b05 64in this case preceding
51f35c5c 65.Ql \e
521a7b05
SW
66is removed and
67.Ql #
68is treated as an ordinary character.
69The fields of the configuration file are as follows:
70.Bl -tag -width indent
71.It Ar logfile_name
2d012f91
PA
72Name of the system log file to be archived,
73or one of the literal strings
74.Dq Aq Li default ,
75or
76.Dq Aq Li include .
521a7b05
SW
77The special default entry will only be used if a log file
78name is given as a command line argument to
79.Xr newsyslog 8 ,
80and if that log file name is not matched by any other
81line in the configuration file.
2d012f91
PA
82The include entry is used to include other configuration
83files and supports globbing.
521a7b05
SW
84.It Ar owner : Ns Ar group
85This optional field specifies the owner and group for the archive file.
86The
87.Ql \&:
88is essential regardless if the
89.Ar owner
90or
91.Ar group
92field is left blank or contains a value.
93The field may be numeric, or a name which is present in
94.Pa /etc/passwd
95or
96.Pa /etc/group .
97.It Ar mode
98Specify the file mode of the log file and archives.
99.It Ar count
100Specify the maximum number of archive files which may exist.
101This does not consider the current log file.
102.It Ar size
103When the size of the log file reaches
104.Ar size
105in kilobytes, the log file will be trimmed as described above.
106If this field contains an asterisk
107.Pq Ql * ,
108the log file will not be trimmed based on size.
109.It Ar when
110The
111.Ar when
112field may consist of an interval, a specific time, or both.
113If the
114.Ar when
115field contains an asterisk
116.Pq Ql * ,
117log rotation will solely depend on the contents of the
118.Ar size
119field.
120Otherwise, the
121.Ar when
122field consists of an optional interval in hours, usually followed
123by an
124.So Li \&@ Sc Ns No -sign
125and a time in restricted
126.Tn ISO 8601
127format.
128Additionally, the format may also be constructed with a
129.Ql $
130sign along with a rotation time specification of once
131a day, once a week, or once a month.
132.Pp
133If a time is specified, the log file will only be trimmed if
134.Xr newsyslog 8
135is run within one hour of the specified time.
136If an interval is specified, the log file will be trimmed if that many
137hours have passed since the last rotation.
138When both a time and an interval are
139specified then both conditions must be satisfied for the rotation to
140take place.
141.Pp
142There is no provision for the specification of a timezone.
143There is little point in specifying an explicit minutes or
144seconds component in the current implementation, since the only comparison is
145.Dq within the hour .
146.Pp
147.Sy ISO 8601 restricted time format :
148.Pp
149The lead-in character for a restricted
150.Tn ISO 8601
151time is an
152.Ql @
153sign.
154The particular format of the time in restricted
155.Tn ISO 8601
156is:
157.Sm off
5a394c59
FF
158.Oo Oo Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd Oc
159.Oo Li T Oo Va hh Oo Va mm Oo Va ss Oc Oc Oc Oc Oc .
521a7b05
SW
160.Sm on
161Optional date fields default to the appropriate component of the
162current date; optional time fields default to midnight; hence if today
163is January 22, 1999, the following date specifications are all
164equivalent:
165.Pp
166.Bl -item -compact -offset indent
167.It
168.Sq Li 19990122T000000
169.It
170.Sq Li 990122T000000
171.It
172.Sq Li 0122T000000
173.It
174.Sq Li 22T000000
175.It
176.Sq Li T000000
177.It
178.Sq Li T0000
179.It
180.Sq Li T00
181.It
182.Sq Li 22T
183.It
184.Sq Li T
185.It
186.Sq Li \&
187.El
188.Pp
189.Sy Day, week, and month time format:
190.Pp
191The lead-in character for day, week, and month specification is a
192.Ql $
193sign.
194The particular format of day, week, and month specification is:
195.Op Li D Ns Va hh ,
196.Op Li W Ns Va w Ns Op Li D Ns Va hh ,
197and
198.Op Li M Ns Va dd Ns Op Li D Ns Va hh ,
199respectively.
200Optional time fields default to midnight.
201The ranges for day and hour specifications are:
202.Pp
203.Bl -tag -width indent -offset indent -compact
204.It Ar hh
205hours, range 0..23
206.It Ar w
207day of week, range 0..6, 0 = Sunday
208.It Ar dd
209day of month, range 1..31, or one of the letters
210.Ql L
211or
212.Ql l
213to specify the last day of the month.
214.El
215.Pp
216Some examples:
217.Pp
218.Bl -tag -width indent -offset indent -compact
219.It Li $D0
220rotate every night at midnight
221(same as
222.Li @T00 )
223.It Li $D23
224rotate every day at 23:00
225(same as
226.Li @T23 )
227.It Li $W0D23
228rotate every week on Sunday at 23:00
229.It Li $W5D16
230rotate every week on Friday at 16:00
231.It Li $M1D0
232rotate at the first day of every month at midnight
233(i.e., the start of the day; same as
234.Li @01T00 )
235.It Li $M5D6
236rotate on every 5th day of month at 6:00
237(same as
238.Li @05T06 )
239.El
240.It Ar flags
241This optional field is made up of one or more characters
242that specify any special processing to be done for the log
243files matched by this line.
244The following are valid flags:
245.Bl -tag -width indent
246.It Cm B
247indicates that the log file is a binary file, or has some
248special format.
249Usually
250.Xr newsyslog 8
251inserts an
252.Tn ASCII
253message into a log file during rotation.
254This message is used to indicate
255when, and sometimes why the log file was rotated.
256If
257.Cm B
258is specified, then that informational message will not be
259inserted into the log file.
260.It Cm C
261indicates that the log file should be created if it does not
262already exist, and if the
263.Fl C
264option was also specified on the command line.
265.It Cm D
266indicates that
267.Xr newsyslog 8
268should set the
269.Dv UF_NODUMP
270flag when creating a new version of
271this log file.
68b2c890 272This option would affect how the
521a7b05
SW
273.Xr dump 8
274command treats the log file when making a file system backup.
275.It Cm G
276indicates that the specified
277.Ar logfile_name
278is a shell pattern, and that
279.Xr newsyslog 8
280should archive all filenames matching that pattern using the
281other options on this line.
282See
283.Xr glob 3
284for details on syntax and matching rules.
285.It Cm J
286indicates that
287.Xr newsyslog 8
288should attempt to save disk space by compressing the rotated
289log file using
290.Xr bzip2 1 .
2d012f91
PA
291.It Cm X
292indicates that
293.Xr newsyslog 8
294should attempt to save disk space by compressing the rotated
295log file using
296.Xr xz 1 .
521a7b05
SW
297.It Cm N
298indicates that there is no process which needs to be signaled
299when this log file is rotated.
300.It Cm U
301indicates that the file specified by
302.Ar path_to_pid_file
303will contain the ID for a process group instead of a process.
304This option also requires that the first line in that file
305be a negative value to distinguish it from a process ID.
306.It Cm Z
307indicates that
308.Xr newsyslog 8
309should attempt to save disk space by compressing the rotated
310log file using
311.Xr gzip 1 .
312.It Fl
313a minus sign will not cause any special processing, but it
314can be used as a placeholder to create a
315.Ar flags
316field when you need to specify any of the following fields.
317.El
318.It Ar path_to_pid_file
319This optional field specifies the file name containing a daemon's
320process ID or to find a group process ID if the
321.Cm U
322flag was specified.
323If this field is present, a
324.Ar signal_number
2d012f91
PA
325is sent to the process ID contained in this file.
326If this field is not present and the
327.Cm N
328flag has not been specified, then a
521a7b05
SW
329.Dv SIGHUP
330signal will be sent to
2d012f91
PA
331.Xr syslogd 8
332or to the process id found in the file specified by
333.Xr newsyslog 8 Ns 's
334.Fl S
335switch.
521a7b05
SW
336This field must start with
337.Ql /
338in order to be recognized properly.
339.It Ar signal_number
340This optional field specifies the signal number that will be sent
341to the daemon process (or to all processes in a process group, if the
342.Cm U
343flag was specified).
344If this field is not present, then a
345.Dv SIGHUP
346signal will be sent.
347.El
348.Sh SEE ALSO
349.Xr bzip2 1 ,
350.Xr gzip 1 ,
2d012f91 351.Xr xz 1 ,
521a7b05
SW
352.Xr syslog 3 ,
353.Xr chown 8 ,
354.Xr newsyslog 8 ,
355.Xr syslogd 8
356.Sh HISTORY
357This manual page first appeared in
358.Fx 4.10 .