Annotation of src/usr.bin/newsyslog/newsyslog.8, Revision 1.13
1.13 ! aaron 1: .\" $OpenBSD: newsyslog.8,v 1.12 1999/05/23 14:11:30 aaron 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.4 downsj 51: .Dd July 7, 1997
52: .Dt NEWSYSLOG 8
1.12 aaron 53: .Os
1.4 downsj 54: .Sh NAME
55: .Nm newsyslog
56: .Nd maintain system log files to manageable sizes
57: .Sh SYNOPSIS
1.10 aaron 58: .Nm newsyslog
1.4 downsj 59: .Op Fl vmnr
60: .Op Fl f Ar configuration file
61: .Sh DESCRIPTION
1.13 ! aaron 62: .Nm
1.1 deraadt 63: is a program that should be scheduled to run periodically by
1.4 downsj 64: .Xr cron 8 .
1.1 deraadt 65: When it is executed it archives log files if necessary. If a log file
1.13 ! aaron 66: is determined to require archiving,
! 67: .Nm
! 68: rearranges the files so that
! 69: .Pa logfile
! 70: is empty,
! 71: .Pa logfile.0
! 72: has
! 73: the last period's logs in it,
! 74: .Pa logfile.1
! 75: has the next to last
1.1 deraadt 76: period's logs in it, and so on, up to a user-specified number of
77: archived logs. Optionally the archived logs can be compressed to save
1.13 ! aaron 78: space.
1.4 downsj 79: .Pp
1.1 deraadt 80: A log can be archived because of two reasons. The log file can have
81: grown bigger than a preset size in kilobytes, or a preset number of
82: hours may have elapsed since the last log archive. The granularity of
1.13 ! aaron 83: .Nm
1.4 downsj 84: is dependent on how often it is scheduled to run in
85: .Xr cron 8 .
86: Since the program is quite fast, it may be scheduled to run every hour
1.1 deraadt 87: without any ill effects.
1.4 downsj 88: .Pp
1.13 ! aaron 89: When starting up,
! 90: .Nm
1.1 deraadt 91: reads in a configuration file to determine which logs should be looked
1.13 ! aaron 92: at. By default, this configuration file is
1.4 downsj 93: .Pa /etc/newsyslog.conf .
1.1 deraadt 94: Each line of the file contains information about a particular log file
95: that should be handled by
1.4 downsj 96: .Nm newsyslog .
97: Each line has five mandatory fields and up to three optional fields, with a
1.1 deraadt 98: whitespace separating each field. Blank lines or lines beginning with
1.13 ! aaron 99: .Ql #
! 100: are ignored. The fields of the configuration file are as
! 101: follows:
1.4 downsj 102: .Bl -tag -width XXXXXXXXXXXXXXXX
103: .It logfile name
104: The full pathname of the system log file to be archived.
105: .It owner.group of archives (optional)
1.13 ! aaron 106: Specify an ownership and group for the archive file. The
! 107: .Ql \&.
! 108: is essential, even if the
1.4 downsj 109: .Ar owner
1.1 deraadt 110: or
1.4 downsj 111: .Ar group
112: field is left blank. The fields may be numeric, or a name which is looked up
113: in the system password and group databases.
114: .It mode of logfile & archives
115: Octal mode of created log files and archives.
116: .It number of archives
1.6 d 117: Specify the number of archives to be kept besides the log file itself.
1.4 downsj 118: .It size of archives
119: When the size of the log file reaches this point, the log file becomes trimmed
1.13 ! aaron 120: as described above. If this field is replaced by a
! 121: .Ql * ,
! 122: then the size of
1.4 downsj 123: the log file is not taken into account when determining when to trim the
124: log file.
125: .It archive interval
126: Specify the time separation between the trimming of the log file. If this
1.13 ! aaron 127: field is replaced by a
! 128: .Ql * ,
! 129: the number of hours since the last time the
1.4 downsj 130: log was trimmed will not be taken into consideration.
131: .It flags (optional)
1.1 deraadt 132: The
1.4 downsj 133: .Ar flags
1.1 deraadt 134: field specifies if the archives should have any special processing
1.13 ! aaron 135: done to the archived log files. The
! 136: .Sq Z
! 137: flag will make the archive
1.4 downsj 138: files compressed to save space using
139: .Xr gzip 1
140: or
141: .Xr compress 1 ,
1.13 ! aaron 142: depending on compilation options. The
! 143: .Sq B
! 144: flag means that the file is a
1.8 aaron 145: binary file, and so the ASCII message which
1.13 ! aaron 146: .Nm
1.1 deraadt 147: inserts to indicate the fact that the logs have been turned over
1.13 ! aaron 148: should not be included. The
! 149: .Sq M
! 150: flag marks this entry as a monitored
1.4 downsj 151: log file.
152: .It monitor notification (optional)
153: Specify the account that should receive notification messages if this is
1.5 downsj 154: a monitored log file. Notification messages are sent as email; the operator
1.13 ! aaron 155: deserves what they get if they mark the
1.5 downsj 156: .Xr sendmail 8
1.6 d 157: log file as monitored.
1.7 millert 158: .It pid file (optional)
159: Specify a file containing the id of a process to send a HUP signal to
160: instead of
161: .Pa /var/run/syslog.pid .
1.4 downsj 162: .El
163: .Pp
164: .Sh OPTIONS
1.8 aaron 165: The following options can be used with
166: .Nm newsyslog :
1.4 downsj 167: .Bl -tag -width XXX
168: .It Fl f Ar config-file
1.13 ! aaron 169: Instructs newsyslog to use
1.4 downsj 170: .Ar config-file
1.8 aaron 171: instead of
172: .Pa /etc/newsyslog.conf
173: for its configuration file.
1.4 downsj 174: .It Fl v
1.13 ! aaron 175: Places
! 176: .Nm
1.1 deraadt 177: in verbose mode. In this mode it will print out each log and its
178: reasons for either trimming that log or skipping it.
1.4 downsj 179: .It Fl n
1.8 aaron 180: Causes
1.13 ! aaron 181: .Nm
1.1 deraadt 182: not to trim the logs, but to print out what it would do if this option
183: were not specified.
1.4 downsj 184: .It Fl r
1.8 aaron 185: Removes the restriction that
1.13 ! aaron 186: .Nm
! 187: must be running as root. Of course,
! 188: .Nm
1.1 deraadt 189: will not be able to send a HUP signal to
1.4 downsj 190: .Xr syslogd 8 ,
1.1 deraadt 191: so this option should only be used in debugging.
1.4 downsj 192: .It Fl m
1.8 aaron 193: Places
1.13 ! aaron 194: .Nm
! 195: in monitoring mode; only entries marked with an
! 196: .Sq M
! 197: in flags are processed,
1.4 downsj 198: and notifications sent if any have changed. Without this option, monitored
199: entries are not processed.
200: .El
201: .Pp
202: .Sh FILES
203: .Bl -tag -width /etc/newsyslog.conf
204: .It Pa /etc/newsyslog.conf
1.11 aaron 205: default configuration file
1.4 downsj 206: .El
207: .Sh SEE ALSO
1.8 aaron 208: .Xr compress 1 ,
1.4 downsj 209: .Xr gzip 1 ,
210: .Xr syslog 3 ,
1.8 aaron 211: .Xr syslogd 8
1.4 downsj 212: .Sh AUTHOR
213: .Bd -unfilled -offset indent
1.1 deraadt 214: Theodore Ts'o, MIT Project Athena
215: Copyright 1987, Massachusetts Institute of Technology
1.4 downsj 216: .Ed