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 August 21, 2018
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,
73or one of the literal strings
74.Dq Aq Li default ,
75or
76.Dq Aq Li include .
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.
82The include entry is used to include other configuration
83files and supports globbing.
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.
99Valid mode bits are
100.Dv 0666 .
101(That is, read and write permissions for the rotated log may be specified for
102the owner, group, and others.)
103All other mode bits are ignored.
104.It Ar count
105Specify the maximum number of archive files which may exist.
106This does not consider the current log file.
107.It Ar size
108When the size of the log file reaches
109.Ar size
110in kilobytes, the log file will be trimmed as described above.
111If this field contains an asterisk
112.Pq Ql * ,
113the log file will not be trimmed based on size.
114.It Ar when
115The
116.Ar when
117field may consist of an interval, a specific time, or both.
118If the
119.Ar when
120field contains an asterisk
121.Pq Ql * ,
122log rotation will solely depend on the contents of the
123.Ar size
124field.
125Otherwise, the
126.Ar when
127field consists of an optional interval in hours, usually followed
128by an
129.So Li \&@ Sc Ns No -sign
130and a time in restricted
131.Tn ISO 8601
132format.
133Additionally, the format may also be constructed with a
134.Ql $
135sign along with a rotation time specification of once
136a day, once a week, or once a month.
137.Pp
138Time based trimming happens only if
139.Xr newsyslog 8
140is run within one hour of the specified time.
141If an interval is specified, the log file will be trimmed if that many
142hours have passed since the last rotation.
143When both a time and an interval are
144specified then both conditions must be satisfied for the rotation to
145take place.
146.Pp
147There is no provision for the specification of a timezone.
148There is little point in specifying an explicit minutes or
149seconds component in the current implementation, since the only comparison is
150.Dq within the hour .
151.Pp
152.Sy ISO 8601 restricted time format :
153.Pp
154The lead-in character for a restricted
155.Tn ISO 8601
156time is an
157.Ql @
158sign.
159The particular format of the time in restricted
160.Tn ISO 8601
161is:
162.Sm off
163.Oo Oo Oo Oo Oo
164.Va cc Oc
165.Va yy Oc
166.Va mm Oc
167.Va dd Oc
168.Oo
169.Li T Oo
170.Va hh Oo
171.Va mm Oo
172.Va ss
173.Oc Oc Oc Oc Oc .
174.Sm on
175Optional date fields default to the appropriate component of the
176current date; optional time fields default to midnight; hence if today
177is January 22, 1999, the following date specifications are all
178equivalent:
179.Pp
180.Bl -item -compact -offset indent
181.It
182.Sq Li 19990122T000000
183.It
184.Sq Li 990122T000000
185.It
186.Sq Li 0122T000000
187.It
188.Sq Li 22T000000
189.It
190.Sq Li T000000
191.It
192.Sq Li T0000
193.It
194.Sq Li T00
195.It
196.Sq Li 22T
197.It
198.Sq Li T
199.It
200.Sq Li \&
201.El
202.Pp
203.Sy Day, week, and month time format:
204.Pp
205The lead-in character for day, week, and month specification is a
206.Ql $
207sign.
208The particular format of day, week, and month specification is:
209.Op Li D Ns Va hh ,
210.Op Li W Ns Va w Ns Op Li D Ns Va hh ,
211and
212.Op Li M Ns Va dd Ns Op Li D Ns Va hh ,
213respectively.
214Optional time fields default to midnight.
215The ranges for day and hour specifications are:
216.Pp
217.Bl -tag -width indent -offset indent -compact
218.It Ar hh
219hours, range 0..23
220.It Ar w
221day of week, range 0..6, 0 = Sunday
222.It Ar dd
223day of month, range 1..31, or one of the letters
224.Ql L
225or
226.Ql l
227to specify the last day of the month.
228.El
229.Pp
230Some examples:
231.Pp
232.Bl -tag -width indent -offset indent -compact
233.It Li $D0
234rotate every night at midnight
235(same as
236.Li @T00 )
237.It Li $D23
238rotate every day at 23:00
239(same as
240.Li @T23 )
241.It Li $W0D23
242rotate every week on Sunday at 23:00
243.It Li $W5D16
244rotate every week on Friday at 16:00
245.It Li $M1D0
246rotate at the first day of every month at midnight
247(i.e., the start of the day; same as
248.Li @01T00 )
249.It Li $M5D6
250rotate on every fifth day of month at 6:00
251(same as
252.Li @05T06 )
253.El
254.It Ar flags
255This optional field is made up of one or more characters
256that specify any special processing to be done for the log
257files matched by this line.
258The following are valid flags:
259.Bl -tag -width indent
260.It Cm B
261indicates that the log file is a binary file, or has some
262special format.
263Usually
264.Xr newsyslog 8
265inserts an
266.Tn ASCII
267message into a log file during rotation.
268This message is used to indicate
269when, and sometimes why the log file was rotated.
270If
271.Cm B
272is specified, then that informational message will not be
273inserted into the log file.
274.It Cm C
275indicates that the log file should be created if it does not
276already exist, and if the
277.Fl C
278option was also specified on the command line.
279.It Cm D
280indicates that
281.Xr newsyslog 8
282should set the
283.Dv UF_NODUMP
284flag when creating a new version of
285this log file.
286This option would affect how the
287.Xr dump 8
288command treats the log file when making a file system backup.
289.It Cm G
290indicates that the specified
291.Ar logfile_name
292is a shell pattern, and that
293.Xr newsyslog 8
294should archive all filenames matching that pattern using the
295other options on this line.
296See
297.Xr glob 3
298for details on syntax and matching rules.
299.It Cm J
300indicates that
301.Xr newsyslog 8
302should attempt to save disk space by compressing the rotated
303log file using
304.Xr bzip2 1 .
305.It Cm N
306indicates that there is no process which needs to be signaled
307when this log file is rotated.
308.It Cm p
309indicates that the zero-th rotated file should not be compressed.
310.It Cm R
311if this flag is set the
312.Xr newsyslog 8
313will run shell command defined in
314.Ar path_to_pid_cmd_file
315after rotation instead of trying to send signal to a process id
316stored in the file.
317.It Cm T
318if this flag is set the informational rotation message written to
319the log file will be in the format specified by RFC5424.
320Normally, the rotation message is written in the traditional (RFC3164)
321syslog format.
322.It Cm U
323indicates that the file specified by
324.Ar path_to_pid_cmd_file
325will contain the ID for a process group instead of a process.
326This option also requires that the first line in that file
327be a negative value to distinguish it from a process ID.
328.It Cm X
329indicates that
330.Xr newsyslog 8
331should attempt to save disk space by compressing the rotated
332log file using
333.Xr xz 1 .
334.It Cm Y
335indicates that
336.Xr newsyslog 8
337should attempt to save disk space by compressing the rotated
338log file using
339.Xr zstd 1 .
340.It Cm Z
341indicates that
342.Xr newsyslog 8
343should attempt to save disk space by compressing the rotated
344log file using
345.Xr gzip 1 .
346.It Fl
347a minus sign will not cause any special processing, but it
348can be used as a placeholder to create a
349.Ar flags
350field when you need to specify any of the following fields.
351.El
352.It Ar path_to_pid_cmd_file
353This optional field specifies the file name containing a daemon's
354process ID or to find a group process ID if the
355.Cm U
356flag was specified.
357If this field is present, a
358.Ar signal
359is sent to the process ID contained in this file.
360If this field is not present and the
361.Cm N
362flag has not been specified, then a
363.Dv SIGHUP
364signal will be sent to
365.Xr syslogd 8
366or to the process id found in the file specified by
367.Xr newsyslog 8 Ns 's
368.Fl S
369switch.
370This field must start with
371.Ql /
372in order to be recognized properly.
373When used with the
374.Cm R
375flag, the file is treated as a path to a binary to be executed
376by the
377.Xr newsyslog 8
378after rotation instead of sending the signal out.
379.It Ar signal
380This optional field specifies the signal that will be sent to the daemon
381process (or to all processes in a process group, if the
382.Cm U
383flag was specified).
384If this field is not present, then a
385.Dv SIGHUP
386signal will be sent.
387Signal names
388must start with
389.Dq SIG
390and be the signal name, e.g.,
391.Dv SIGUSR1 .
392Alternatively,
393.Ar signal
394can be the signal number, e.g., 30 for
395.Dv SIGUSR1 .
396.El
397.Sh EXAMPLES
398The following is an example of the
399.Dq Aq Li include
400entry:
401.Dl "<include> /etc/newsyslog-local.conf"
402.Sh SEE ALSO
403.Xr bzip2 1 ,
404.Xr gzip 1 ,
405.Xr xz 1 ,
406.Xr syslog 3 ,
407.Xr chown 8 ,
408.Xr newsyslog 8 ,
409.Xr syslogd 8
410.Pp
411.Rs
412.%A C. Lonvick
413.%T The BSD syslog Protocol
414.%O RFC3164
415.Re
416.Rs
417.%A R. Gerhards
418.%T The Syslog Protocol
419.%O RFC5424
420.Re
421.Sh HISTORY
422This manual page first appeared in
423.Fx 4.10 .
424