Sweep-fix man page section order to match mdoc(7), part 5/5.
[dragonfly.git] / usr.sbin / newsyslog / newsyslog.8
1 .\" This file contains changes from the Open Software Foundation.
2 .\"
3 .\"     from: @(#)newsyslog.8
4 .\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.8,v 1.23.2.14 2003/05/07 20:42:56 gad Exp $
5 .\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.8,v 1.3 2006/02/17 19:40:19 swildner Exp $
6 .\"
7 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software
10 .\" and its documentation for any purpose and without fee is
11 .\" hereby granted, provided that the above copyright notice
12 .\" appear in all copies and that both that copyright notice and
13 .\" this permission notice appear in supporting documentation,
14 .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
15 .\" used in advertising or publicity pertaining to distribution
16 .\" of the software without specific, written prior permission.
17 .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
18 .\" the suitability of this software for any purpose.  It is
19 .\" provided "as is" without express or implied warranty.
20 .\"
21 .Dd April 27, 2003
22 .Dt NEWSYSLOG 8
23 .Os
24 .Sh NAME
25 .Nm newsyslog
26 .Nd maintain system log files to manageable sizes
27 .Sh SYNOPSIS
28 .Nm
29 .Op Fl CFnrsv
30 .Op Fl R Ar tagname
31 .Op Fl a Ar directory
32 .Op Fl f Ar config_file
33 .Op Ar
34 .Sh DESCRIPTION
35 The
36 .Nm
37 utility should be scheduled to run periodically by
38 .Xr cron 8 .
39 When it is executed it archives log files if necessary.  If a log file
40 is determined to require archiving,
41 .Nm
42 rearranges the files so that
43 .Dq Va logfile
44 is empty,
45 .Dq Va logfile Ns Li \&.0
46 has
47 the last period's logs in it,
48 .Dq Va logfile Ns Li \&.1
49 has the next to last
50 period's logs in it, and so on, up to a user-specified number of
51 archived logs.  Optionally the archived logs can be compressed to save
52 space.
53 .Pp
54 A log can be archived for three reasons:
55 .Bl -enum -offset indent
56 .It
57 It is larger than the configured size (in kilobytes).
58 .It
59 A configured number of hours have elapsed since the log was last
60 archived.
61 .It
62 This is the specific configured hour for rotation of the log.
63 .El
64 .Pp
65 The granularity of
66 .Nm
67 is dependent on how often it is scheduled to run by
68 .Xr cron 8 .
69 Since the program is quite fast, it may be scheduled to run every hour
70 without any ill effects,
71 and mode three (above) assumes that this is so.
72 .Pp
73 When starting up,
74 .Nm
75 reads in a configuration file to determine which logs may potentially
76 be archived.
77 By default, this configuration file is
78 .Pa /etc/newsyslog.conf .
79 Each line of the file contains information about a particular log file
80 that should be handled by
81 .Nm .
82 Each line has five mandatory fields and four optional fields, with
83 whitespace separating each field.  Blank lines or lines beginning with
84 ``#'' are ignored.  If ``#'' is placed in the middle of the line,
85 ``#'' character and the rest of the line after it is ignored.
86 To prevent special meaning, the ``#'' may be escaped with ``\\'',
87 in this case preceding ``\\'' is removed and ``#'' treated as ordinary
88 character.  The fields of the configuration file are as
89 follows:
90 .Pp
91 .Bl -tag -width indent
92 .It Ar logfile_name
93 Name of the system log file to be archived, or the literal string
94 ``<default>''.
95 The special default entry will be only be used if some log file
96 name is given as a command line argument on the
97 .Nm
98 command, and if that log file name is not matched by any other
99 line in the configuration file.
100 .It Ar owner : Ns Ar group
101 This optional field specifies the owner and group for the archive file.
102 The ":" is essential, even if the
103 .Ar owner
104 or
105 .Ar group
106 field is left blank.  The field may be numeric, or a name which is
107 present in
108 .Pa /etc/passwd
109 or
110 .Pa /etc/group .
111 .It Ar mode
112 Specify the mode of the log file and archives.
113 .It Ar count
114 Specify the number of archive files to be kept
115 besides the log file itself.
116 .It Ar size
117 When the size of the log file reaches
118 .Ar size
119 in kilobytes,
120 the log file will be trimmed as described above.  If this field
121 is replaced by an asterisk
122 .Pq Ql \&* ,
123 then the size of the log file is not taken into account
124 when determining when to trim the log file.
125 .It Ar when
126 The
127 .Ar when
128 field can consist of an interval, a specific time, or both.  If
129 the
130 .Ar when
131 field is an asterisk
132 .Pq Ql \&*
133 log rotation will depend only on the contents of the
134 .Ar size
135 field.
136 Otherwise, the
137 .Ar when
138 field consists of an optional interval in hours, optionally followed
139 by an
140 .So Li \&@ Sc Ns No -sign
141 and a time in a restricted
142 .Tn ISO 8601
143 format or by an
144 .So Li \&$ Sc Ns No -sign
145 and a time specification for logfile rotation at a fixed time once
146 per day, per week or per month.
147 .Pp
148 If a time is specified, the log file will only be trimmed if
149 .Nm
150 is run within one hour of the specified time.  If an
151 interval is specified, the log file will be trimmed if that many hours have
152 passed since the last rotation.  When both a time and an interval are
153 specified, both conditions must be satisfied for the rotation to take
154 place.
155 .Pp
156 There is no provision for specification of a timezone.  There is
157 little point in specifying an explicit minutes or seconds component in
158 the current implementation, since the only comparison is `within the
159 hour'.
160 .Pp
161 .Sy ISO 8601 restricted time format
162 .Pp
163 The lead-in character for a restricted
164 .Tn ISO 8601
165 time is
166 an
167 .So Li \&@ Sc Ns No -sign .
168 The particular format of the time in restricted
169 .Tn ISO 8601
170 is:
171 .Sm off
172 .Oo
173 .Oo
174 .Oo
175 .Oo
176 .Oo
177 .Va \&cc
178 .Oc
179 .Va \&yy
180 .Oc
181 .Va \&mm
182 .Oc
183 .Va \&dd
184 .Oc
185 .Oo
186 .Li \&T
187 .Oo
188 .Va \&hh
189 .Oo
190 .Va \&mm
191 .Oo
192 .Va \&ss
193 .Oc
194 .Oc
195 .Oc
196 .Oc
197 .Oc .
198 .Sm on
199 Optional date fields default to the appropriate component of the
200 current date; optional time fields default to midnight; hence if today
201 is January 22, 1999, the following date specifications are all
202 equivalent:
203 .Pp
204 .Bl -item -compact -offset indent
205 .It
206 .Sq Li 19990122T000000
207 .It
208 .Sq Li 990122T000000
209 .It
210 .Sq Li 0122T000000
211 .It
212 .Sq Li 22T000000
213 .It
214 .Sq Li T000000
215 .It
216 .Sq Li T0000
217 .It
218 .Sq Li T00
219 .It
220 .Sq Li 22T
221 .It
222 .Sq Li \&T
223 .It
224 .Sq Li \&
225 .El
226 .Pp
227 .Sy Day, week and month time format
228 .Pp
229 The lead-in character for day, week and month specification is a
230 .So Li \&$ Sc Ns No -sign .
231 The particular format of day, week and month specification is:
232 .Op Va D\&hh ,
233 .Op Va W\&w Ns Op Va D\&hh
234 and
235 .Op Va M\&dd Ns Op Va D\&hh
236 respectively.
237 Optional time fields default to midnight.
238 The ranges for day and hour specifications are:
239 .Pp
240 .Bl -tag -width Ds -compact -offset indent
241 .It Ar hh
242 hours, range 0 ... 23
243 .It Ar w
244 day of week, range 0 ... 6, 0 = Sunday
245 .It Ar dd
246 day of month, range 1 ... 31, or the letter
247 .Em L
248 or
249 .Em l
250 to specify the last day of the month.
251 .El
252 .Pp
253 Some examples:
254 .Pp
255 .Bl -tag -width Ds -compact -offset indent
256 .It Ar $D0
257 rotate every night at midnight
258 (same as
259 .Ar @T00 )
260 .It Ar $D23
261 rotate every day at 23:00 hr
262 (same as
263 .Ar @T23 )
264 .It Ar $W0D23
265 rotate every week on Sunday at 23:00 hr
266 .It Ar $W5D16
267 rotate every week on Friday at 16:00 hr
268 .It Ar $M1D0
269 rotate at the first day of every month at midnight
270 (i.e., the start of the day; same as
271 .Ar @01T00 )
272 .It Ar $M5D6
273 rotate on every 5th day of month at 6:00 hr
274 (same as
275 .Ar @05T06 )
276 .El
277 .Pp
278 .It Ar flags
279 This optional field is made up of one or more characters
280 that specify any special processing to be done for the log
281 files matched by this line.
282 The following are valid flags:
283 .Bl -tag -width indent
284 .It Sy B
285 indicates that the log file is a binary file, or has some
286 special format.
287 Usually
288 .Nm
289 inserts an
290 .Tn ASCII
291 message into a log file when rotating the file, to indicate
292 when and sometimes why the log file was rotated.
293 If
294 .Sy B
295 is specified, then that informational message will not be
296 inserted into the log file.
297 .It Sy C
298 indicates that the log file should be created if it does not
299 already exist, and if the
300 .Fl C
301 option was also specified on the command line.
302 .It Sy G
303 indicates that the specified
304 .Ar logfile_name
305 is a shell pattern, and that
306 .Nm
307 should archive all filenames matching that pattern, using the
308 other options specified on this line.
309 See
310 .Xr glob 3
311 for details on syntax and matching rules.
312 .It Sy J
313 indicates that
314 .Nm
315 should attempt to save disk space by compressing the rotated
316 log file using
317 .Xr bzip2 1 .
318 .It Sy N
319 indicates that there is no process which needs to be signalled
320 when this log file is rotated.
321 .It Sy U
322 indicates that the file specified by
323 .Ar path_to_pid_file
324 will contain the id for a process group, instead of a process.
325 This option also requires that the first line in that file must
326 be a negative value, to distinguish it from a value for a
327 process id.
328 .It Sy W
329 if used with the
330 .Sy Z
331 or
332 .Sy J
333 flag, this indicates that
334 .Nm
335 should wait for previously started compression jobs to complete before
336 starting a new one for this entry.
337 If this is used with the
338 .Sy G
339 flag, and if multiple log files match the given pattern, then
340 .Nm
341 will compress those logs one by one.
342 This ensures that only one compression job is running at a time.
343 .It Sy Z
344 indicates that
345 .Nm
346 should attempt to save disk space by compressing the rotated
347 log file using
348 .Xr gzip 1 .
349 .It Sy -
350 a minus sign will not cause any special processing, but it
351 can be used as a placeholder to create a
352 .Ar flags
353 field when you need to specify any of the following fields.
354 .El
355 .It Ar path_to_pid_file
356 This optional field specifies the file name to read to find the daemon
357 process id, or to find a process group id if the
358 .Sy U
359 flag was specified.
360 If this field is present, a
361 .Ar signal_number
362 is sent the process id contained in this file.
363 If this field is not present, then a SIGHUP signal will be
364 sent to
365 .Xr syslogd 8 ,
366 unless the
367 .Sy N
368 flag has been specified.
369 This field must start with "/" in order to be recognized
370 properly.
371 .It Ar signal_number
372 This optional field specifies the signal number that will be sent
373 to the daemon process (or to all processes in a process group, if
374 the
375 .Sy U
376 flag was specified).
377 If this field is not present, then a SIGHUP signal will be sent.
378 .El
379 .Sh OPTIONS
380 The following options can be used with
381 .Nm :
382 .Bl -tag -width indent
383 .It Fl f Ar config_file
384 Instruct
385 .Nm
386 to use
387 .Ar config_file
388 instead of
389 .Pa /etc/newsyslog.conf
390 for its configuration file.
391 .It Fl a Ar directory
392 Specify a
393 .Ar directory
394 into which archived log files will be written.
395 If a relative path is given,
396 it is appended to the path of each log file
397 and the resulting path is used as the directory
398 into which the archived log for that log file will be written.
399 If an absolute path is given,
400 all archived logs are written into the given
401 .Ar directory .
402 If any component of the path
403 .Ar directory
404 does not exist,
405 it will be created when
406 .Nm
407 is run.
408 .It Fl v
409 Place
410 .Nm
411 in verbose mode.  In this mode it will print out each log and its
412 reasons for either trimming that log or skipping it.
413 .It Fl n
414 Cause
415 .Nm
416 not to trim the logs, but to print out what it would do if this option
417 were not specified.
418 .It Fl r
419 Remove the restriction that
420 .Nm
421 must be running as root.  Of course,
422 .Nm
423 will not be able to send a HUP signal to
424 .Xr syslogd 8
425 so this option should only be used in debugging.
426 .It Fl s
427 Specify that
428 .Nm
429 should not send any signals to any daemon processes that it would
430 normally signal when rotating a log file.
431 For any log file which is rotated, this option will usually also
432 mean the rotated log file will not be compressed if there is a
433 daemon which would have been signalled without this option.
434 However, this option is most likely to be useful when specified
435 with the
436 .Fl R
437 option, and in that case the compression will be done.
438 .It Fl C
439 If specified once, then
440 .Nm
441 will create any log files which do not exist, and which have the
442 .Sy C
443 flag specified in their config file entry.
444 If specified multiple times, then
445 .Nm
446 will create all log files which do not already exist.
447 If log files are given on the command-line, then the
448 .Fl C
449 or
450 .Fl CC
451 will only apply to those specific log files.
452 .It Fl F
453 Force
454 .Nm
455 to trim the logs, even if the trim conditions have not been met.  This
456 option is useful for diagnosing system problems by providing you with
457 fresh logs that contain only the problems.
458 .It Fl R Ar tagname
459 Specify that
460 .Nm
461 should rotate a given list of files, even if trim conditions are not
462 met for those files.
463 The
464 .Ar tagname
465 is only used in the messages written to the log files which are
466 rotated.
467 This differs from the
468 .Fl F
469 option in that one or more log files must also be specified, so that
470 .Nm
471 will only operate on those specific files.
472 This option is mainly intended for the daemons or programs which write
473 some log files, and want to trigger a rotate based on their own criteria.
474 With this option they can execute
475 .Nm
476 to trigger the rotate when they want it to happen, and still give the
477 system administrator a way to specify the rules of rotation (such as how
478 many backup copies are kept, and what kind of compression is done).
479 When a daemon does execute
480 .Nm
481 with the
482 .Fl R
483 option, it should make sure all of the log files are closed before
484 calling
485 .Nm ,
486 and then it should re-open the files after
487 .Nm
488 returns.
489 Usually the calling process will also want to specify the
490 .Fl s
491 option, so
492 .Nm
493 will not send a signal to the very process which called it to force
494 the rotate.
495 Skipping the signal step will also mean that
496 .Nm
497 will return faster, since
498 .Nm
499 normally waits a few seconds after any signal that is sent.
500 .El
501 .Pp
502 If additional command line arguments are given,
503 .Nm
504 will only examine log files that match those arguments; otherwise, it
505 will examine all files listed in the configuration file.
506 .Sh FILES
507 .Bl -tag -width /etc/newsyslog.confxxxx -compact
508 .It Pa /etc/newsyslog.conf
509 .Nm
510 configuration file
511 .El
512 .Sh COMPATIBILITY
513 Previous versions of the
514 .Nm
515 utility used the dot (``.'') character to
516 distinguish the group name.
517 Beginning with
518 .Fx 3.3 ,
519 this has been changed to a colon (``:'') character so that user and group
520 names may contain the dot character.  The dot (``.'') character is still
521 accepted for backwards compatibility.
522 .Sh "SEE ALSO"
523 .Xr gzip 1 ,
524 .Xr syslog 3 ,
525 .Xr chown 8 ,
526 .Xr syslogd 8
527 .Sh AUTHORS
528 .An Theodore Ts'o ,
529 MIT Project Athena
530 .Pp
531 Copyright 1987, Massachusetts Institute of Technology
532 .Sh BUGS
533 Doesn't yet automatically read the logs to find security breaches.