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