1 .\" This file contains changes from the Open Software Foundation.
3 .\" from: @(#)newsyslog.8
4 .\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.8,v 1.57 2011/01/31 11:30:26 mm Exp $
6 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
8 .\" Permission to use, copy, modify, and distribute this software
9 .\" and its documentation for any purpose and without fee is
10 .\" hereby granted, provided that the above copyright notice
11 .\" appear in all copies and that both that copyright notice and
12 .\" this permission notice appear in supporting documentation,
13 .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
14 .\" used in advertising or publicity pertaining to distribution
15 .\" of the software without specific, written prior permission.
16 .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
17 .\" the suitability of this software for any purpose. It is
18 .\" provided "as is" without express or implied warranty.
25 .Nd maintain system log files to manageable sizes
33 .Op Fl f Ar config_file
39 utility should be scheduled to run periodically by
41 When it is executed it archives log files if necessary.
42 If a log file is determined to require archiving,
44 rearranges the files so that
47 .Dq Va logfile Ns Li \&.0
49 the last period's logs in it,
50 .Dq Va logfile Ns Li \&.1
52 period's logs in it, and so on, up to a user-specified number of
54 It is also possible to let archived log filenames be created using the
55 time the log file was archived instead of the sequential number using
59 Optionally the archived logs can be compressed to save space.
61 A log can be archived for three reasons:
62 .Bl -enum -offset indent
64 It is larger than the configured size (in kilobytes).
66 A configured number of hours have elapsed since the log was last
69 This is the specific configured hour for rotation of the log.
74 is dependent on how often it is scheduled to run by
76 Since the program is quite fast, it may be scheduled to run every hour
77 without any ill effects,
78 and mode three (above) assumes that this is so.
80 The following options can be used with
82 .Bl -tag -width indent
83 .It Fl f Ar config_file
89 .Pa /etc/newsyslog.conf
90 for its configuration file.
94 into which archived log files will be written.
95 If a relative path is given,
96 it is appended to the path of each log file
97 and the resulting path is used as the directory
98 into which the archived log for that log file will be written.
99 If an absolute path is given,
100 all archived logs are written into the given
102 If any component of the path
105 it will be created when
108 .It Fl d Ar directory
111 which all log files will be relative to.
112 To allow archiving of logs outside the root, the
116 option is unaffected.
121 In this mode it will print out each log and its
122 reasons for either trimming that log or skipping it.
126 not to trim the logs, but to print out what it would do if this option
129 Remove the restriction that
131 must be running as root.
134 will not be able to send a HUP signal to
136 so this option should only be used in debugging.
140 should not send any signals to any daemon processes that it would
141 normally signal when rotating a log file.
142 For any log file which is rotated, this option will usually also
143 mean the rotated log file will not be compressed if there is a
144 daemon which would have been signalled without this option.
145 However, this option is most likely to be useful when specified
148 option, and in that case the compression will be done.
154 logfiles using the specified time format instead of the default
155 sequential filenames.
156 The time format is described in the
161 argument is set to an empty string or the string
163 the default built in time format
167 string is changed the old files created using the previous time format
168 will not be be automatically removed (unless the new format is very
169 similar to the old format).
170 This is also the case when changing from sequential filenames to time
171 based file names, and the other way around.
172 The time format should contain at least year, month, day, and hour to
173 make sure rotating of old logfiles can select the correct logfiles.
175 If specified once, then
177 will create any log files which do not exist, and which have the
179 flag specified in their config file entry.
180 If specified multiple times, then
182 will create all log files which do not already exist.
183 If log files are given on the command-line, then the
187 will only apply to those specific log files.
191 to trim the logs, even if the trim conditions have not been met.
192 This option is useful for diagnosing system problems by providing you with
193 fresh logs that contain only the problems.
195 Do not perform any rotations.
196 This option is intended to be used with the
200 options when creating log files is the only objective.
202 Prevent further action if we should send signal but the
204 is empty or does not exist.
208 should rotate a given list of files, even if trim conditions are not
212 is only used in the messages written to the log files which are
214 This differs from the
216 option in that one or more log files must also be specified, so that
218 will only operate on those specific files.
219 This option is mainly intended for the daemons or programs which write
220 some log files, and want to trigger a rotate based on their own criteria.
221 With this option they can execute
223 to trigger the rotate when they want it to happen, and still give the
224 system administrator a way to specify the rules of rotation (such as how
225 many backup copies are kept, and what kind of compression is done).
226 When a daemon does execute
230 option, it should make sure all of the log files are closed before
233 and then it should re-open the files after
236 Usually the calling process will also want to specify the
240 will not send a signal to the very process which called it to force
242 Skipping the signal step will also mean that
244 will return faster, since
246 normally waits a few seconds after any signal that is sent.
255 If additional command line arguments are given,
257 will only examine log files that match those arguments; otherwise, it
258 will examine all files listed in the configuration file.
260 .Bl -tag -width /etc/newsyslog.confxxxx -compact
261 .It Pa /etc/newsyslog.conf
266 Previous versions of the
268 utility used the dot (``.'') character to
269 distinguish the group name.
272 this has been changed to a colon (``:'') character so that user and group
273 names may contain the dot character.
274 The dot (``.'') character is still accepted for backwards compatibility.
280 .Xr newsyslog.conf 5 ,
286 utility originated from
288 and first appeared in
294 Copyright 1987, Massachusetts Institute of Technology
296 Does not yet automatically read the logs to find security breaches.