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