Annotation of src/usr.bin/newsyslog/newsyslog.8, Revision 1.54
1.54 ! jca 1: .\" $OpenBSD: newsyslog.8,v 1.53 2015/11/14 01:22:04 jmc Exp $
1.4 downsj 2: .\"
3: .\" Copyright (c) 1997, Jason Downs. All rights reserved.
4: .\"
5: .\" Redistribution and use in source and binary forms, with or without
6: .\" modification, are permitted provided that the following conditions
7: .\" are met:
8: .\" 1. Redistributions of source code must retain the above copyright
9: .\" notice, this list of conditions and the following disclaimer.
10: .\" 2. Redistributions in binary form must reproduce the above copyright
11: .\" notice, this list of conditions and the following disclaimer in the
12: .\" documentation and/or other materials provided with the distribution.
13: .\"
14: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS
15: .\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
16: .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
17: .\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT,
18: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
19: .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
20: .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
21: .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24: .\" SUCH DAMAGE.
25: .\"
1.1 deraadt 26: .\" This file contains changes from the Open Software Foundation.
27: .\"
28: .\" from: @(#)newsyslog.8
29: .\"
30: .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
1.13 aaron 31: .\"
1.1 deraadt 32: .\" Permission to use, copy, modify, and distribute this software
33: .\" and its documentation for any purpose and without fee is
34: .\" hereby granted, provided that the above copyright notice
35: .\" appear in all copies and that both that copyright notice and
36: .\" this permission notice appear in supporting documentation,
37: .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
38: .\" used in advertising or publicity pertaining to distribution
39: .\" of the software without specific, written prior permission.
40: .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
41: .\" the suitability of this software for any purpose. It is
42: .\" provided "as is" without express or implied warranty.
43: .\"
1.54 ! jca 44: .Dd $Mdocdate: November 14 2015 $
1.4 downsj 45: .Dt NEWSYSLOG 8
1.12 aaron 46: .Os
1.4 downsj 47: .Sh NAME
1.53 jmc 48: .Nm newsyslog ,
49: .Nm newsyslog.conf
1.45 schwarze 50: .Nd rotate log files
1.4 downsj 51: .Sh SYNOPSIS
1.10 aaron 52: .Nm newsyslog
1.27 millert 53: .Op Fl Fmnrv
1.26 millert 54: .Op Fl a Ar directory
1.20 aaron 55: .Op Fl f Ar config_file
1.28 millert 56: .Op Ar log ...
1.4 downsj 57: .Sh DESCRIPTION
1.45 schwarze 58: The
1.13 aaron 59: .Nm
1.45 schwarze 60: utility rotates log files when they exceed a configurable size or age.
61: The
62: .Ar log
63: file is renamed to
64: .Pa log.0
65: and an empty file is created in its place.
66: An archive of older logs may be kept:
67: in order of increasing age, these files are named
68: .Pa log.1 ,
69: .Pa log.2 ,
70: and so on.
71: When their number exceeds a given limit, the oldest is removed.
72: The archived logs may also be compressed.
1.4 downsj 73: .Pp
1.18 aaron 74: The options are as follows:
75: .Bl -tag -width Ds
1.40 jmc 76: .It Fl a Ar directory
77: Specify a
78: .Ar directory
79: into which archived log files will be written.
80: If
81: .Ar directory
82: is a relative path, it is appended to the parent directory
83: of each log and the archived log is stored in the result.
84: If an absolute path is given, all archived logs are stored in the given
85: .Ar directory .
86: If
87: .Ar directory
88: does not exist for a specified log, it is ignored for that entry and
89: the log is rotated as if the
90: .Fl a
91: option was not specified.
1.27 millert 92: .It Fl F
93: Force
94: .Nm
95: to trim logs regardless of the size and/or age requirements specified in
96: .Pa /etc/newsyslog.conf .
97: This option may be combined with the
98: .Fl n
99: or
100: .Fl v
101: flags to aid in debugging problems with
102: .Pa /etc/newsyslog.conf .
1.40 jmc 103: .It Fl f Ar config_file
104: Use
105: .Ar config_file
106: instead of
107: .Pa /etc/newsyslog.conf
108: for the configuration file.
1.20 aaron 109: .It Fl m
110: Monitoring mode; only entries marked with an
111: .Sq M
1.31 millert 112: in flags are processed.
1.36 jmc 113: For each log file being monitored, any log output since the last time
1.31 millert 114: .Nm
115: was run with the
116: .Fl m
117: flag is mailed to the user listed in the monitor notification section.
1.18 aaron 118: .It Fl n
119: Do not trim the logs, but instead print out what would be done if this option
120: were not specified.
121: .It Fl r
122: Removes the restriction that
123: .Nm
124: must be running as root.
1.34 millert 125: Note that in this mode
1.18 aaron 126: .Nm
127: will not be able to send a
128: .Dv SIGHUP
129: signal to
1.34 millert 130: .Xr syslogd 8 .
1.20 aaron 131: .It Fl v
1.33 millert 132: Place
133: .Nm newsyslog
134: in verbose mode.
1.20 aaron 135: In this mode it will print out each log and its
136: reasons for either trimming that log or skipping it.
1.18 aaron 137: .El
1.28 millert 138: .Pp
1.45 schwarze 139: In the default system configuration,
140: .Nm
141: is run by
142: .Xr cron 8 ,
143: but it may also be run manually.
1.28 millert 144: If one or more
145: .Ar log
1.45 schwarze 146: files are specified on the command line, only the specified files are
147: rotated.
1.28 millert 148: Note that each
149: .Ar log
150: specified must have an entry in
151: .Pa /etc/newsyslog.conf .
1.18 aaron 152: .Pp
1.32 jmc 153: A log can be archived because of two reasons:
1.18 aaron 154: The log file can have
1.1 deraadt 155: grown bigger than a preset size in kilobytes, or a preset number of
1.18 aaron 156: hours may have elapsed since the last log archive.
157: The granularity of
1.13 aaron 158: .Nm
1.4 downsj 159: is dependent on how often it is scheduled to run in
160: .Xr cron 8 .
161: Since the program is quite fast, it may be scheduled to run every hour
1.1 deraadt 162: without any ill effects.
1.4 downsj 163: .Pp
1.13 aaron 164: When starting up,
165: .Nm
1.1 deraadt 166: reads in a configuration file to determine which logs should be looked
1.18 aaron 167: at.
168: By default, this configuration file is
1.4 downsj 169: .Pa /etc/newsyslog.conf .
1.1 deraadt 170: Each line of the file contains information about a particular log file
171: that should be handled by
1.4 downsj 172: .Nm newsyslog .
1.34 millert 173: Each line has five mandatory fields and up to three optional fields, with
1.18 aaron 174: whitespace separating each field.
175: Blank lines or lines beginning with a hash mark
176: .Pq Ql #
177: are ignored.
178: The fields of the configuration file are as
1.13 aaron 179: follows:
1.4 downsj 180: .Bl -tag -width XXXXXXXXXXXXXXXX
1.33 millert 181: .It Ar logfile_name
1.4 downsj 182: The full pathname of the system log file to be archived.
1.33 millert 183: .It Ar owner:group
184: This optional field specifies the owner and group for the archive file.
1.18 aaron 185: The
1.34 millert 186: .Ql \&:
1.13 aaron 187: is essential, even if the
1.4 downsj 188: .Ar owner
1.1 deraadt 189: or
1.4 downsj 190: .Ar group
1.18 aaron 191: field is left blank.
192: The fields may be numeric, or a name which is looked up
1.4 downsj 193: in the system password and group databases.
1.33 millert 194: For backwards compatibility, a
195: .Ql \&.
196: may be used instead of a
1.34 millert 197: .Ql \&: .
1.38 millert 198: If either
199: .Ar owner
200: or
201: .Ar group
202: is not specified, the owner and/or group of the existing log file is used.
1.33 millert 203: .It Ar mode
204: File mode (in octal) to use for created log files and archives.
205: .It Ar count
206: The number of archives to be kept besides the log file itself.
207: .It Ar size
1.24 millert 208: When the size of the log file (in kilobytes) reaches this point, the log
209: file is trimmed as described above.
1.33 millert 210: If this field is replaced by an
1.42 jmc 211: .Ql * ,
212: or set to
213: .Ql 0 ,
1.13 aaron 214: then the size of
1.4 downsj 215: the log file is not taken into account when determining when to trim the
216: log file.
1.46 lum 217: By default, files smaller than 256 bytes are not rotated unless the
1.24 millert 218: .Sq B
1.42 jmc 219: (binary) flag is set or the
220: .Fl F
221: option is specified.
1.24 millert 222: This prevents
223: .Nm
224: from rotating files consisting solely of a message indicating
225: that the log file has been turned over.
1.33 millert 226: .It Ar when
1.1 deraadt 227: The
1.33 millert 228: .Ar when
229: field can consist of an interval, a specific time, or both.
230: If the
231: .Ar when
232: field consists of an asterisk
233: .Pq Ql \&* ,
234: log rotation will depend only on the contents of the
235: .Ar size
236: field.
237: Otherwise, the
238: .Ar when
239: field consists of an optional interval in hours, possibly followed
240: by an
1.37 jmc 241: .So Li \&@ Sc Ns -sign
1.33 millert 242: and a time in a restricted
1.48 jmc 243: .St -iso8601
1.33 millert 244: format or by a
1.37 jmc 245: .So Li \&$ Sc Ns -sign
1.33 millert 246: and a time specification for logfile rotation at a fixed time once
247: per day, per week or per month.
248: .Pp
249: If a time is specified, the log file will only be trimmed if
250: .Nm
251: is run within one hour of the specified time.
252: If an interval is specified, the log file will be trimmed if that
253: many hours have passed since the last rotation.
254: When both a time and an interval are specified, both conditions
255: must be satisfied for the rotation to take place.
256: .Pp
1.41 jmc 257: There is no provision for the specification of a time zone.
1.33 millert 258: There is little point in specifying an explicit minutes or seconds
259: component in the current implementation, since the only comparison is
260: .Sq within the hour .
1.39 jmc 261: .Pp
262: .Sy ISO 8601 restricted time format:
1.33 millert 263: The lead-in character for a restricted
1.48 jmc 264: .St -iso8601
1.33 millert 265: time is an
1.37 jmc 266: .So Li \&@ Sc Ns -sign .
1.33 millert 267: The particular format of the time in restricted
1.48 jmc 268: .St -iso8601
1.33 millert 269: is:
270: .Sm off
271: .Oo Oo Oo Oo Oo
272: .Va \&cc Oc
273: .Va \&yy Oc
274: .Va \&mm Oc
275: .Va \&dd Oc
1.49 jmc 276: .Oo Va \&T
277: .Oo Va \&HH
278: .Oo Va \&MM
279: .Oo Va \&SS
1.33 millert 280: .Oc Oc Oc Oc Oc .
281: .Sm on
282: Optional date fields default to the appropriate component of the
1.43 jmc 283: current date; optional time fields default to midnight.
1.33 millert 284: For example, if today is January 22, 1999, the following date specifications
285: are all equivalent:
286: .Pp
287: .Bl -item -compact -offset indent
288: .It
289: .Ql 19990122T000000
290: .It
291: .Ql 990122T000000
292: .It
293: .Ql 0122T000000
294: .It
295: .Ql 22T000000
296: .It
297: .Ql T000000
298: .It
299: .Ql T0000
300: .It
301: .Ql T00
302: .It
303: .Ql 22T
304: .It
305: .Ql \&T
306: .It
307: .Ql \&
308: .El
1.39 jmc 309: .Pp
310: .Sy Day, week and month time format:
1.33 millert 311: The lead-in character for day, week and month specification is a
1.49 jmc 312: dollar sign
313: .Pq $ .
1.33 millert 314: The particular format of day, week and month specification is:
1.49 jmc 315: .Op Li D Ns Ar HH ,
316: .Op Li W Ns Ar w Ns Op Li D Ns Ar HH ,
1.33 millert 317: and
1.49 jmc 318: .Op Li M Ns Ar dd Ns Op Li D Ns Ar HH ,
1.33 millert 319: respectively.
320: Optional time fields default to midnight.
321: The ranges for day and hour specifications are:
322: .Pp
323: .Bl -tag -width Ds -compact -offset indent
1.49 jmc 324: .It Ar HH
1.33 millert 325: hours, range 0 ... 23
326: .It Ar w
327: day of week, range 0 ... 6, 0 = Sunday
328: .It Ar dd
329: day of month, range 1 ... 31, or the letter
330: .Em L
331: or
332: .Em l
333: to specify the last day of the month.
334: .El
1.39 jmc 335: .Pp
336: .Sy Some examples:
1.33 millert 337: .Bl -tag -width Ds -compact -offset indent
1.49 jmc 338: .It Li $D0
1.33 millert 339: rotate every night at midnight
340: (same as
1.49 jmc 341: .Li @T00 )
342: .It Li $D23
1.33 millert 343: rotate every day at 23:00 hr
344: (same as
1.49 jmc 345: .Li @T23 )
346: .It Li $W0D23
1.33 millert 347: rotate every week on Sunday at 23:00 hr
1.49 jmc 348: .It Li $W5D16
1.33 millert 349: rotate every week on Friday at 16:00 hr
1.49 jmc 350: .It Li $M1D0
1.33 millert 351: rotate on the first day of every month at midnight
352: (i.e., the start of the day; same as
1.49 jmc 353: .Li @01T00 )
354: .It Li $M5D6
1.33 millert 355: rotate on every 5th day of the month at 6:00 hr
356: (same as
1.49 jmc 357: .Li @05T06 )
1.33 millert 358: .El
359: .It Ar flags
360: The optional
1.4 downsj 361: .Ar flags
1.1 deraadt 362: field specifies if the archives should have any special processing
1.18 aaron 363: done to the archived log files.
364: The
1.13 aaron 365: .Sq Z
366: flag will make the archive
1.4 downsj 367: files compressed to save space using
368: .Xr gzip 1
369: or
370: .Xr compress 1 ,
1.18 aaron 371: depending on compilation options.
372: The
1.13 aaron 373: .Sq B
374: flag means that the file is a
1.8 aaron 375: binary file, and so the ASCII message which
1.13 aaron 376: .Nm
1.1 deraadt 377: inserts to indicate the fact that the logs have been turned over
1.18 aaron 378: should not be included.
379: The
1.13 aaron 380: .Sq M
381: flag marks this entry as a monitored
1.4 downsj 382: log file.
1.22 wcobb 383: The
384: .Sq F
385: flag specifies that symbolic links should be followed.
1.33 millert 386: .It Ar monitor
1.31 millert 387: Specify the username (or email address) that should receive notification
388: messages if this is a monitored log file.
1.18 aaron 389: Notification messages are sent as email; the operator
1.52 jmc 390: deserves what they get if they mark the mail
1.6 d 391: log file as monitored.
1.33 millert 392: This field is only valid when the
393: .Sq M
394: flag is set.
395: .It Ar pid_file
396: This optional field specifies a file containing the PID of a process to send a
397: signal (usually
398: .Dv SIGHUP )
399: to instead of
1.7 millert 400: .Pa /var/run/syslog.pid .
1.33 millert 401: .It Ar signal
1.18 aaron 402: Specify the signal to send to the process instead of
403: .Dv SIGHUP .
404: Signal names
1.16 millert 405: must start with
406: .Dq SIG
1.18 aaron 407: and be the signal name, not the number, e.g.,
1.23 millert 408: .Dv SIGUSR1 .
1.33 millert 409: .It Ar command
410: This optional field specifies a command to run instead of sending a signal
411: to the process.
1.18 aaron 412: The command must be enclosed in double quotes
1.30 deraadt 413: .Pq Ql \&" .
1.29 millert 414: The empty string,
415: .Ql \&"\&" ,
1.42 jmc 416: can be used to prevent
1.29 millert 417: .Nm
418: from sending a signal or running a command.
1.18 aaron 419: You cannot specify both a command and a PID file.
1.25 millert 420: .Em NOTE:
1.19 millert 421: If you specify a command to be run,
422: .Nm
423: will not send a
424: .Dv SIGHUP to
425: .Xr syslogd 8 .
1.4 downsj 426: .El
427: .Sh FILES
428: .Bl -tag -width /etc/newsyslog.conf
429: .It Pa /etc/newsyslog.conf
1.11 aaron 430: default configuration file
1.4 downsj 431: .El
1.54 ! jca 432: .Sh EXIT STATUS
! 433: .Ex -std
1.4 downsj 434: .Sh SEE ALSO
1.8 aaron 435: .Xr compress 1 ,
1.4 downsj 436: .Xr gzip 1 ,
437: .Xr syslog 3 ,
1.8 aaron 438: .Xr syslogd 8
1.21 mpech 439: .Sh AUTHORS
1.51 schwarze 440: .An Theodore Ts'o ,
441: MIT Project Athena
442: .br
1.1 deraadt 443: Copyright 1987, Massachusetts Institute of Technology
![[BACK]](/icons/back.gif){kind=icon}
Return to newsyslog.8 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / newsyslog