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
8.\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.conf.5,v 1.6 2006/09/29 17:57:03 ru Exp $
9.\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.conf.5,v 1.3 2008/07/09 18:27:30 thomas Exp $
10.\"
11.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
12.\"
13.\" Permission to use, copy, modify, and distribute this software
14.\" and its documentation for any purpose and without fee is
15.\" hereby granted, provided that the above copyright notice
16.\" appear in all copies and that both that copyright notice and
17.\" this permission notice appear in supporting documentation,
18.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
19.\" used in advertising or publicity pertaining to distribution
20.\" of the software without specific, written prior permission.
21.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
22.\" the suitability of this software for any purpose.  It is
23.\" provided "as is" without express or implied warranty.
24.\"
25.Dd May 2, 2007
26.Dt NEWSYSLOG.CONF 5
27.Os
28.Sh NAME
29.Nm newsyslog.conf
30.Nd
31.Xr newsyslog 8
32configuration file
33.Sh DESCRIPTION
34The
35.Nm
36file is used to set log file rotation configuration for the
37.Xr newsyslog 8
38utility.
39Configuration may designate that logs are rotated based on
40size, last rotation time, or time of day.
41The
42.Nm
43file can also be used to designate secure permissions to log
44files at rotation time.
45During initialization,
46.Xr newsyslog 8
47reads a configuration file,
48normally
49.Pa /etc/newsyslog.conf ,
50to determine which logs may potentially be rotated and archived.
51Each line has five mandatory fields and four optional fields,
52separated with whitespace.
53Blank lines or lines beginning with
54.Ql #
55are ignored.
56If
57.Ql #
58is placed in the middle of the line, the
59.Ql #
60character and the rest of the line after it is ignored.
61To prevent special meaning, the
62.Ql #
63character may be escaped with
64.Ql \e ;
65in this case preceding
66.Ql \e
67is removed and
68.Ql #
69is treated as an ordinary character.
70The fields of the configuration file are as follows:
71.Bl -tag -width indent
72.It Ar logfile_name
73Name of the system log file to be archived, or the literal string
74.Dq Aq Li default .
75The special default entry will only be used if a log file
76name is given as a command line argument to
77.Xr newsyslog 8 ,
78and if that log file name is not matched by any other
79line in the configuration file.
80.It Ar owner : Ns Ar group
81This optional field specifies the owner and group for the archive file.
82The
83.Ql \&:
84is essential regardless if the
85.Ar owner
86or
87.Ar group
88field is left blank or contains a value.
89The field may be numeric, or a name which is present in
90.Pa /etc/passwd
91or
92.Pa /etc/group .
93.It Ar mode
94Specify the file mode of the log file and archives.
95.It Ar count
96Specify the maximum number of archive files which may exist.
97This does not consider the current log file.
98.It Ar size
99When the size of the log file reaches
100.Ar size
101in kilobytes, the log file will be trimmed as described above.
102If this field contains an asterisk
103.Pq Ql * ,
104the log file will not be trimmed based on size.
105.It Ar when
106The
107.Ar when
108field may consist of an interval, a specific time, or both.
109If the
110.Ar when
111field contains an asterisk
112.Pq Ql * ,
113log rotation will solely depend on the contents of the
114.Ar size
115field.
116Otherwise, the
117.Ar when
118field consists of an optional interval in hours, usually followed
119by an
120.So Li \&@ Sc Ns No -sign
121and a time in restricted
122.Tn ISO 8601
123format.
124Additionally, the format may also be constructed with a
125.Ql $
126sign along with a rotation time specification of once
127a day, once a week, or once a month.
128.Pp
129If a time is specified, the log file will only be trimmed if
130.Xr newsyslog 8
131is run within one hour of the specified time.
132If an interval is specified, the log file will be trimmed if that many
133hours have passed since the last rotation.
134When both a time and an interval are
135specified then both conditions must be satisfied for the rotation to
136take place.
137.Pp
138There is no provision for the specification of a timezone.
139There is little point in specifying an explicit minutes or
140seconds component in the current implementation, since the only comparison is
141.Dq within the hour .
142.Pp
143.Sy ISO 8601 restricted time format :
144.Pp
145The lead-in character for a restricted
146.Tn ISO 8601
147time is an
148.Ql @
149sign.
150The particular format of the time in restricted
151.Tn ISO 8601
152is:
153.Sm off
154.Oo
155.Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd
156.Oo
157.Li T
158.Op Va hh Oo Va mm Oo Va ss Oc Oc Oc
159.Oc .
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.
272This option would affect how the
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 .
291.It Cm N
292indicates that there is no process which needs to be signaled
293when this log file is rotated.
294.It Cm U
295indicates that the file specified by
296.Ar path_to_pid_file
297will contain the ID for a process group instead of a process.
298This option also requires that the first line in that file
299be a negative value to distinguish it from a process ID.
300.It Cm Z
301indicates that
302.Xr newsyslog 8
303should attempt to save disk space by compressing the rotated
304log file using
305.Xr gzip 1 .
306.It Fl
307a minus sign will not cause any special processing, but it
308can be used as a placeholder to create a
309.Ar flags
310field when you need to specify any of the following fields.
311.El
312.It Ar path_to_pid_file
313This optional field specifies the file name containing a daemon's
314process ID or to find a group process ID if the
315.Cm U
316flag was specified.
317If this field is present, a
318.Ar signal_number
319is sent the process ID contained in this file.
320If this field is not present, then a
321.Dv SIGHUP
322signal will be sent to
323.Xr syslogd 8 ,
324unless the
325.Cm N
326flag has been specified.
327This field must start with
328.Ql /
329in order to be recognized properly.
330.It Ar signal_number
331This optional field specifies the signal number that will be sent
332to the daemon process (or to all processes in a process group, if the
333.Cm U
334flag was specified).
335If this field is not present, then a
336.Dv SIGHUP
337signal will be sent.
338.El
339.Sh SEE ALSO
340.Xr bzip2 1 ,
341.Xr gzip 1 ,
342.Xr syslog 3 ,
343.Xr chown 8 ,
344.Xr newsyslog 8 ,
345.Xr syslogd 8
346.Sh HISTORY
347This manual page first appeared in
348.Fx 4.10 .
349