1 .\" This file contains changes from the Open Software Foundation.
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.2 2003/06/17 04:29:57 dillon Exp $
7 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
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.
26 .Nd maintain system log files to manageable sizes
32 .Op Fl f Ar config_file
37 utility should be scheduled to run periodically by
39 When it is executed it archives log files if necessary. If a log file
40 is determined to require archiving,
42 rearranges the files so that
45 .Dq Va logfile Ns Li \&.0
47 the last period's logs in it,
48 .Dq Va logfile Ns Li \&.1
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
54 A log can be archived for three reasons:
55 .Bl -enum -offset indent
57 It is larger than the configured size (in kilobytes).
59 A configured number of hours have elapsed since the log was last
62 This is the specific configured hour for rotation of the log.
67 is dependent on how often it is scheduled to run by
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.
75 reads in a configuration file to determine which logs may potentially
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
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
91 .Bl -tag -width indent
93 Name of the system log file to be archived, or the literal string
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
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
106 field is left blank. The field may be numeric, or a name which is
112 Specify the mode of the log file and archives.
114 Specify the number of archive files to be kept
115 besides the log file itself.
117 When the size of the log file reaches
120 the log file will be trimmed as described above. If this field
121 is replaced by an asterisk
123 then the size of the log file is not taken into account
124 when determining when to trim the log file.
128 field can consist of an interval, a specific time, or both. If
133 log rotation will depend only on the contents of the
138 field consists of an optional interval in hours, optionally followed
140 .So Li \&@ Sc Ns No -sign
141 and a time in a restricted
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.
148 If a time is specified, the log file will only be trimmed if
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
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
161 .Sy ISO 8601 restricted time format
163 The lead-in character for a restricted
167 .So Li \&@ Sc Ns No -sign .
168 The particular format of the time in restricted
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
204 .Bl -item -compact -offset indent
206 .Sq Li 19990122T000000
227 .Sy Day, week and month time format
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:
233 .Op Va W\&w Ns Op Va D\&hh
235 .Op Va M\&dd Ns Op Va D\&hh
237 Optional time fields default to midnight.
238 The ranges for day and hour specifications are:
240 .Bl -tag -width Ds -compact -offset indent
242 hours, range 0 ... 23
244 day of week, range 0 ... 6, 0 = Sunday
246 day of month, range 1 ... 31, or the letter
250 to specify the last day of the month.
255 .Bl -tag -width Ds -compact -offset indent
257 rotate every night at midnight
261 rotate every day at 23:00 hr
265 rotate every week on Sunday at 23:00 hr
267 rotate every week on Friday at 16:00 hr
269 rotate at the first day of every month at midnight
270 (i.e., the start of the day; same as
273 rotate on every 5th day of month at 6:00 hr
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
285 indicates that the log file is a binary file, or has some
291 message into a log file when rotating the file, to indicate
292 when and sometimes why the log file was rotated.
295 is specified, then that informational message will not be
296 inserted into the log file.
298 indicates that the log file should be created if it does not
299 already exist, and if the
301 option was also specified on the command line.
303 indicates that the specified
305 is a shell pattern, and that
307 should archive all filenames matching that pattern, using the
308 other options specified on this line.
311 for details on syntax and matching rules.
315 should attempt to save disk space by compressing the rotated
319 indicates that there is no process which needs to be signalled
320 when this log file is rotated.
322 indicates that the file specified by
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
333 flag, this indicates that
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
339 flag, and if multiple log files match the given pattern, then
341 will compress those logs one by one.
342 This ensures that only one compression job is running at a time.
346 should attempt to save disk space by compressing the rotated
350 a minus sign will not cause any special processing, but it
351 can be used as a placeholder to create a
353 field when you need to specify any of the following fields.
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
360 If this field is present, a
362 is sent the process id contained in this file.
363 If this field is not present, then a SIGHUP signal will be
368 flag has been specified.
369 This field must start with "/" in order to be recognized
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
377 If this field is not present, then a SIGHUP signal will be sent.
380 The following options can be used with
382 .Bl -tag -width indent
383 .It Fl f Ar config_file
389 .Pa /etc/newsyslog.conf
390 for its configuration file.
391 .It Fl a 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
402 If any component of the path
405 it will be created when
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.
416 not to trim the logs, but to print out what it would do if this option
419 Remove the restriction that
421 must be running as root. Of course,
423 will not be able to send a HUP signal to
425 so this option should only be used in debugging.
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
437 option, and in that case the compression will be done.
439 If specified once, then
441 will create any log files which do not exist, and which have the
443 flag specified in their config file entry.
444 If specified multiple times, then
446 will create all log files which do not already exist.
447 If log files are given on the command-line, then the
451 will only apply to those specific log files.
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.
461 should rotate a given list of files, even if trim conditions are not
465 is only used in the messages written to the log files which are
467 This differs from the
469 option in that one or more log files must also be specified, so that
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
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
483 option, it should make sure all of the log files are closed before
486 and then it should re-open the files after
489 Usually the calling process will also want to specify the
493 will not send a signal to the very process which called it to force
495 Skipping the signal step will also mean that
497 will return faster, since
499 normally waits a few seconds after any signal that is sent.
502 If additional command line arguments are given,
504 will only examine log files that match those arguments; otherwise, it
505 will examine all files listed in the configuration file.
507 .Bl -tag -width /etc/newsyslog.confxxxx -compact
508 .It Pa /etc/newsyslog.conf
513 Doesn't yet automatically read the logs to find security breaches.
518 Copyright 1987, Massachusetts Institute of Technology
520 Previous versions of the
522 utility used the dot (``.'') character to
523 distinguish the group name.
526 this has been changed to a colon (``:'') character so that user and group
527 names may contain the dot character. The dot (``.'') character is still
528 accepted for backwards compatibility.