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$
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.\"
24.Dd November 27, 2006
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
63.Ql \e ;
64in this case preceding
65.Ql \e
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
72Name of the system log file to be archived, or the literal string
73.Dq Aq Li default .
74The special default entry will only be used if a log file
75name is given as a command line argument to
76.Xr newsyslog 8 ,
77and if that log file name is not matched by any other
78line in the configuration file.
79.It Ar owner : Ns Ar group
80This optional field specifies the owner and group for the archive file.
81The
82.Ql \&:
83is essential regardless if the
84.Ar owner
85or
86.Ar group
87field is left blank or contains a value.
88The field may be numeric, or a name which is present in
89.Pa /etc/passwd
90or
91.Pa /etc/group .
92.It Ar mode
93Specify the file mode of the log file and archives.
94.It Ar count
95Specify the maximum number of archive files which may exist.
96This does not consider the current log file.
97.It Ar size
98When the size of the log file reaches
99.Ar size
100in kilobytes, the log file will be trimmed as described above.
101If this field contains an asterisk
102.Pq Ql * ,
103the log file will not be trimmed based on size.
104.It Ar when
105The
106.Ar when
107field may consist of an interval, a specific time, or both.
108If the
109.Ar when
110field contains an asterisk
111.Pq Ql * ,
112log rotation will solely depend on the contents of the
113.Ar size
114field.
115Otherwise, the
116.Ar when
117field consists of an optional interval in hours, usually followed
118by an
119.So Li \&@ Sc Ns No -sign
120and a time in restricted
121.Tn ISO 8601
122format.
123Additionally, the format may also be constructed with a
124.Ql $
125sign along with a rotation time specification of once
126a day, once a week, or once a month.
127.Pp
128If a time is specified, the log file will only be trimmed if
129.Xr newsyslog 8
130is run within one hour of the specified time.
131If an interval is specified, the log file will be trimmed if that many
132hours have passed since the last rotation.
133When both a time and an interval are
134specified then both conditions must be satisfied for the rotation to
135take place.
136.Pp
137There is no provision for the specification of a timezone.
138There is little point in specifying an explicit minutes or
139seconds component in the current implementation, since the only comparison is
140.Dq within the hour .
141.Pp
142.Sy ISO 8601 restricted time format :
143.Pp
144The lead-in character for a restricted
145.Tn ISO 8601
146time is an
147.Ql @
148sign.
149The particular format of the time in restricted
150.Tn ISO 8601
151is:
152.Sm off
153.Oo
154.Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd
155.Oo
156.Li T
157.Op Va hh Oo Va mm Oo Va ss Oc Oc Oc
158.Oc .
159.Sm on
160Optional date fields default to the appropriate component of the
161current date; optional time fields default to midnight; hence if today
162is January 22, 1999, the following date specifications are all
163equivalent:
164.Pp
165.Bl -item -compact -offset indent
166.It
167.Sq Li 19990122T000000
168.It
169.Sq Li 990122T000000
170.It
171.Sq Li 0122T000000
172.It
173.Sq Li 22T000000
174.It
175.Sq Li T000000
176.It
177.Sq Li T0000
178.It
179.Sq Li T00
180.It
181.Sq Li 22T
182.It
183.Sq Li T
184.It
185.Sq Li \&
186.El
187.Pp
188.Sy Day, week, and month time format:
189.Pp
190The lead-in character for day, week, and month specification is a
191.Ql $
192sign.
193The particular format of day, week, and month specification is:
194.Op Li D Ns Va hh ,
195.Op Li W Ns Va w Ns Op Li D Ns Va hh ,
196and
197.Op Li M Ns Va dd Ns Op Li D Ns Va hh ,
198respectively.
199Optional time fields default to midnight.
200The ranges for day and hour specifications are:
201.Pp
202.Bl -tag -width indent -offset indent -compact
203.It Ar hh
204hours, range 0..23
205.It Ar w
206day of week, range 0..6, 0 = Sunday
207.It Ar dd
208day of month, range 1..31, or one of the letters
209.Ql L
210or
211.Ql l
212to specify the last day of the month.
213.El
214.Pp
215Some examples:
216.Pp
217.Bl -tag -width indent -offset indent -compact
218.It Li $D0
219rotate every night at midnight
220(same as
221.Li @T00 )
222.It Li $D23
223rotate every day at 23:00
224(same as
225.Li @T23 )
226.It Li $W0D23
227rotate every week on Sunday at 23:00
228.It Li $W5D16
229rotate every week on Friday at 16:00
230.It Li $M1D0
231rotate at the first day of every month at midnight
232(i.e., the start of the day; same as
233.Li @01T00 )
234.It Li $M5D6
235rotate on every 5th day of month at 6:00
236(same as
237.Li @05T06 )
238.El
239.It Ar flags
240This optional field is made up of one or more characters
241that specify any special processing to be done for the log
242files matched by this line.
243The following are valid flags:
244.Bl -tag -width indent
245.It Cm B
246indicates that the log file is a binary file, or has some
247special format.
248Usually
249.Xr newsyslog 8
250inserts an
251.Tn ASCII
252message into a log file during rotation.
253This message is used to indicate
254when, and sometimes why the log file was rotated.
255If
256.Cm B
257is specified, then that informational message will not be
258inserted into the log file.
259.It Cm C
260indicates that the log file should be created if it does not
261already exist, and if the
262.Fl C
263option was also specified on the command line.
264.It Cm D
265indicates that
266.Xr newsyslog 8
267should set the
268.Dv UF_NODUMP
269flag when creating a new version of
270this log file.
271This option would affect how the
272.Xr dump 8
273command treats the log file when making a file system backup.
274.It Cm G
275indicates that the specified
276.Ar logfile_name
277is a shell pattern, and that
278.Xr newsyslog 8
279should archive all filenames matching that pattern using the
280other options on this line.
281See
282.Xr glob 3
283for details on syntax and matching rules.
284.It Cm J
285indicates that
286.Xr newsyslog 8
287should attempt to save disk space by compressing the rotated
288log file using
289.Xr bzip2 1 .
290.It Cm N
291indicates that there is no process which needs to be signaled
292when this log file is rotated.
293.It Cm U
294indicates that the file specified by
295.Ar path_to_pid_file
296will contain the ID for a process group instead of a process.
297This option also requires that the first line in that file
298be a negative value to distinguish it from a process ID.
299.It Cm Z
300indicates that
301.Xr newsyslog 8
302should attempt to save disk space by compressing the rotated
303log file using
304.Xr gzip 1 .
305.It Fl
306a minus sign will not cause any special processing, but it
307can be used as a placeholder to create a
308.Ar flags
309field when you need to specify any of the following fields.
310.El
311.It Ar path_to_pid_file
312This optional field specifies the file name containing a daemon's
313process ID or to find a group process ID if the
314.Cm U
315flag was specified.
316If this field is present, a
317.Ar signal_number
318is sent the process ID contained in this file.
319If this field is not present, then a
320.Dv SIGHUP
321signal will be sent to
322.Xr syslogd 8 ,
323unless the
324.Cm N
325flag has been specified.
326This field must start with
327.Ql /
328in order to be recognized properly.
329.It Ar signal_number
330This optional field specifies the signal number that will be sent
331to the daemon process (or to all processes in a process group, if the
332.Cm U
333flag was specified).
334If this field is not present, then a
335.Dv SIGHUP
336signal will be sent.
337.El
338.Sh SEE ALSO
339.Xr bzip2 1 ,
340.Xr gzip 1 ,
341.Xr syslog 3 ,
342.Xr chown 8 ,
343.Xr newsyslog 8 ,
344.Xr syslogd 8
345.Sh HISTORY
346This manual page first appeared in
347.Fx 4.10 .
348