Annotation of src/usr.bin/newsyslog/newsyslog.8, Revision 1.19
1.19 ! millert 1: .\" $OpenBSD: newsyslog.8,v 1.18 2000/03/10 19:07:22 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.16 millert 51: .Dd November 11, 1999
1.4 downsj 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.18 aaron 65: When it is executed it archives log files if necessary.
66: If a log file is determined to require archiving,
1.13 aaron 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
1.18 aaron 77: archived logs.
78: Optionally the archived logs can be compressed to save
1.13 aaron 79: space.
1.4 downsj 80: .Pp
1.18 aaron 81: The options are as follows:
82: .Bl -tag -width Ds
83: .It Fl f Ar config-file
84: Use
85: .Ar config-file
86: instead of
87: .Pa /etc/newsyslog.conf
88: for the configuration file.
89: .It Fl v
90: Be verbose.
91: In this mode it will print out each log and its
92: reasons for either trimming that log or skipping it.
93: .It Fl n
94: Do not trim the logs, but instead print out what would be done if this option
95: were not specified.
96: .It Fl r
97: Removes the restriction that
98: .Nm
99: must be running as root.
100: Of course,
101: .Nm
102: will not be able to send a
103: .Dv SIGHUP
104: signal to
105: .Xr syslogd 8 ,
106: so this option should only be used in debugging.
107: .It Fl m
108: Monitoring mode; only entries marked with an
109: .Sq M
110: in flags are processed,
111: and notifications sent if any have changed.
112: Without this option, monitored entries are not processed.
113: .El
114: .Pp
115: A log can be archived because of two reasons.
116: The log file can have
1.1 deraadt 117: grown bigger than a preset size in kilobytes, or a preset number of
1.18 aaron 118: hours may have elapsed since the last log archive.
119: The granularity of
1.13 aaron 120: .Nm
1.4 downsj 121: is dependent on how often it is scheduled to run in
122: .Xr cron 8 .
123: Since the program is quite fast, it may be scheduled to run every hour
1.1 deraadt 124: without any ill effects.
1.4 downsj 125: .Pp
1.13 aaron 126: When starting up,
127: .Nm
1.1 deraadt 128: reads in a configuration file to determine which logs should be looked
1.18 aaron 129: at.
130: By default, this configuration file is
1.4 downsj 131: .Pa /etc/newsyslog.conf .
1.1 deraadt 132: Each line of the file contains information about a particular log file
133: that should be handled by
1.4 downsj 134: .Nm newsyslog .
135: Each line has five mandatory fields and up to three optional fields, with a
1.18 aaron 136: whitespace separating each field.
137: Blank lines or lines beginning with a hash mark
138: .Pq Ql #
139: are ignored.
140: The fields of the configuration file are as
1.13 aaron 141: follows:
1.4 downsj 142: .Bl -tag -width XXXXXXXXXXXXXXXX
143: .It logfile name
144: The full pathname of the system log file to be archived.
145: .It owner.group of archives (optional)
1.18 aaron 146: Specify an ownership and group for the archive file.
147: The
1.13 aaron 148: .Ql \&.
149: is essential, even if the
1.4 downsj 150: .Ar owner
1.1 deraadt 151: or
1.4 downsj 152: .Ar group
1.18 aaron 153: field is left blank.
154: The fields may be numeric, or a name which is looked up
1.4 downsj 155: in the system password and group databases.
156: .It mode of logfile & archives
157: Octal mode of created log files and archives.
158: .It number of archives
1.6 d 159: Specify the number of archives to be kept besides the log file itself.
1.4 downsj 160: .It size of archives
161: When the size of the log file reaches this point, the log file becomes trimmed
1.18 aaron 162: as described above.
163: If this field is replaced by a
1.13 aaron 164: .Ql * ,
165: then the size of
1.4 downsj 166: the log file is not taken into account when determining when to trim the
167: log file.
168: .It archive interval
1.18 aaron 169: Specify the time separation between the trimming of the log file.
170: If this field is replaced by a
1.13 aaron 171: .Ql * ,
172: the number of hours since the last time the
1.4 downsj 173: log was trimmed will not be taken into consideration.
174: .It flags (optional)
1.1 deraadt 175: The
1.4 downsj 176: .Ar flags
1.1 deraadt 177: field specifies if the archives should have any special processing
1.18 aaron 178: done to the archived log files.
179: The
1.13 aaron 180: .Sq Z
181: flag will make the archive
1.4 downsj 182: files compressed to save space using
183: .Xr gzip 1
184: or
185: .Xr compress 1 ,
1.18 aaron 186: depending on compilation options.
187: The
1.13 aaron 188: .Sq B
189: flag means that the file is a
1.8 aaron 190: binary file, and so the ASCII message which
1.13 aaron 191: .Nm
1.1 deraadt 192: inserts to indicate the fact that the logs have been turned over
1.18 aaron 193: should not be included.
194: The
1.13 aaron 195: .Sq M
196: flag marks this entry as a monitored
1.4 downsj 197: log file.
198: .It monitor notification (optional)
199: Specify the account that should receive notification messages if this is
1.18 aaron 200: a monitored log file.
201: Notification messages are sent as email; the operator
1.13 aaron 202: deserves what they get if they mark the
1.5 downsj 203: .Xr sendmail 8
1.6 d 204: log file as monitored.
1.7 millert 205: .It pid file (optional)
1.14 aaron 206: Specify a file containing the PID of a process to send a
207: .Dv SIGHUP
208: signal to instead of
1.7 millert 209: .Pa /var/run/syslog.pid .
1.16 millert 210: .It signal (optional)
1.18 aaron 211: Specify the signal to send to the process instead of
212: .Dv SIGHUP .
213: Signal names
1.16 millert 214: must start with
215: .Dq SIG
1.18 aaron 216: and be the signal name, not the number, e.g.,
1.16 millert 217: .Em SIGUSR1 .
218: .It command (optional)
219: Specify a command to run instead of sending a signal to the process.
1.18 aaron 220: The command must be enclosed in double quotes
221: .Pq Ql \&" ) .
222: You cannot specify both a command and a PID file.
1.19 ! millert 223: .Em NOTE:
! 224: If you specify a command to be run,
! 225: .Nm
! 226: will not send a
! 227: .Dv SIGHUP to
! 228: .Xr syslogd 8 .
1.4 downsj 229: .El
230: .Sh FILES
231: .Bl -tag -width /etc/newsyslog.conf
232: .It Pa /etc/newsyslog.conf
1.11 aaron 233: default configuration file
1.4 downsj 234: .El
235: .Sh SEE ALSO
1.8 aaron 236: .Xr compress 1 ,
1.4 downsj 237: .Xr gzip 1 ,
238: .Xr syslog 3 ,
1.8 aaron 239: .Xr syslogd 8
1.4 downsj 240: .Sh AUTHOR
1.18 aaron 241: .Bd -unfilled
1.1 deraadt 242: Theodore Ts'o, MIT Project Athena
243: Copyright 1987, Massachusetts Institute of Technology
1.4 downsj 244: .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