1 .\" This file contains changes from the Open Software Foundation.
3 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
5 .\" Permission to use, copy, modify, and distribute this software
6 .\" and its documentation for any purpose and without fee is
7 .\" hereby granted, provided that the above copyright notice
8 .\" appear in all copies and that both that copyright notice and
9 .\" this permission notice appear in supporting documentation,
10 .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
11 .\" used in advertising or publicity pertaining to distribution
12 .\" of the software without specific, written prior permission.
13 .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
14 .\" the suitability of this software for any purpose. It is
15 .\" provided "as is" without express or implied warranty.
22 .Nd maintain system log files to manageable sizes
27 .Op Fl c Ar none Ns | Ns Ar legacy Ns | Ns Ar bzip2 Ns | Ns Ar gzip Ns | Ns Ar xz Ns | Ns Ar zstd
29 .Op Fl f Ar config_file
32 .Op Oo Fl R Ar tagname Oc Ar
36 utility should be scheduled to run periodically by
38 When it is executed it archives log files if necessary.
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
52 It is also possible to let archived log filenames be created using the
53 time the log file was archived instead of the sequential number using
57 Optionally the archived logs can be compressed to save
60 A log can be archived for three reasons:
61 .Bl -enum -offset indent
63 It is larger than the configured size (in kilobytes).
65 A configured number of hours have elapsed since the log was last
68 This is the specific configured hour for rotation of the log.
73 is dependent on how often it is scheduled to run by
75 Since the program is quite fast, it may be scheduled to run every hour
76 without any ill effects,
77 and mode three (above) assumes that this is so.
79 The following options can be used with
81 .Bl -tag -width indent
82 .It Fl c Ar none Ns | Ns Ar legacy Ns | Ns Ar bzip2 Ns | Ns Ar gzip Ns | Ns Ar xz Ns | Ns Ar zstd
85 to use the specified compression method when a file is flagged for compression.
90 flags in the configuration file according to their historical meanings.
91 This default setting can be overridden by specifying
95 to ignore all compression flags.
96 Alternatively, specifying one of the compression methods:
97 .Sy bzip2 , gzip , xz ,
100 will apply the chosen method to all files flagged for compression.
101 .It Fl f Ar config_file
107 .Pa /etc/newsyslog.conf
108 for its configuration file.
109 .It Fl a Ar directory
112 into which archived log files will be written.
113 If a relative path is given,
114 it is appended to the path of each log file
115 and the resulting path is used as the directory
116 into which the archived log for that log file will be written.
117 If an absolute path is given,
118 all archived logs are written into the given
120 If any component of the path
123 it will be created when
126 .It Fl d Ar directory
129 which all log files will be relative to.
130 To allow archiving of logs outside the root, the
134 option is unaffected.
139 In this mode it will print out each log and its
140 reasons for either trimming that log or skipping it.
144 not to trim the logs, but to print out what it would do if this option
146 This option implies the
150 Remove the restriction that
152 must be running as root.
155 will not be able to send a HUP signal to
157 so this option should only be used in debugging.
161 should not send any signals to any daemon processes that it would
162 normally signal when rotating a log file.
163 For any log file which is rotated, this option will usually also
164 mean the rotated log file will not be compressed if there is a
165 daemon which would have been signalled without this option.
166 However, this option is most likely to be useful when specified
169 option, and in that case the compression will be done.
175 logfiles using the specified time format instead of the default
176 sequential filenames.
177 The filename used will be kept until it is deleted.
178 The time format is described in the
183 argument is set to an empty string or the string
185 the default built in time format
189 string is changed the old files created using the previous time format
190 will not be automatically removed (unless the new format is very
191 similar to the old format).
192 This is also the case when changing from sequential filenames to time
193 based file names, and the other way around.
194 The time format should contain at least year, month, day, and hour to
195 make sure rotating of old logfiles can select the correct logfiles.
197 If specified once, then
199 will create any log files which do not exist, and which have the
201 flag specified in their config file entry.
202 If specified multiple times, then
204 will create all log files which do not already exist.
205 If log files are given on the command-line, then the
209 will only apply to those specific log files.
213 to trim the logs, even if the trim conditions have not been met.
215 option is useful for diagnosing system problems by providing you with
216 fresh logs that contain only the problems.
218 Do not perform any rotations.
219 This option is intended to be used with the
223 options when creating log files is the only objective.
225 Prevent further action if we should send signal but the
227 is empty or does not exist.
231 should rotate a given list of files, even if trim conditions are not
235 is only used in the messages written to the log files which are
237 This differs from the
239 option in that one or more log files must also be specified, so that
241 will only operate on those specific files.
242 This option is mainly intended for the daemons or programs which write
243 some log files, and want to trigger a rotate based on their own criteria.
244 With this option they can execute
246 to trigger the rotate when they want it to happen, and still give the
247 system administrator a way to specify the rules of rotation (such as how
248 many backup copies are kept, and what kind of compression is done).
249 When a daemon does execute
253 option, it should make sure all of the log files are closed before
256 and then it should re-open the files after
259 Usually the calling process will also want to specify the
263 will not send a signal to the very process which called it to force
265 Skipping the signal step will also mean that
267 will return faster, since
269 normally waits a few seconds after any signal that is sent.
278 If additional command line arguments are given,
280 will only examine log files that match those arguments; otherwise, it
281 will examine all files listed in the configuration file.
283 .Bl -tag -width /usr/local/etc/newsyslog.conf.d -compact
284 .It Pa /etc/newsyslog.conf
287 .It Pa /etc/newsyslog.conf.d
288 By default each file in this directory ending in '.conf' and not beginning with
289 a '.' will be included by the default
291 .It Pa /usr/local/etc/newsyslog.conf.d
292 By default each file in this directory ending in '.conf' and not beginning with
293 a '.' will be included by the default
297 Previous versions of the
299 utility used the dot (``.'') character to
300 distinguish the group name.
303 this has been changed to a colon (``:'') character so that user and group
304 names may contain the dot character.
305 The dot (``.'') character is still
306 accepted for backwards compatibility.
313 .Xr newsyslog.conf 5 ,
319 utility originated from
321 and first appeared in
327 Copyright 1987, Massachusetts Institute of Technology
projects / FreeBSD / FreeBSD.git / blob