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