Annotation of src/usr.bin/newsyslog/newsyslog.8, Revision 1.32
1.32 ! jmc 1: .\" $OpenBSD: newsyslog.8,v 1.31 2003/01/25 05:09: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
56: .Nd maintain system log files to manageable sizes
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.20 aaron 80: Optionally the archived logs can be 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.
111: Of course,
112: .Nm
113: will not be able to send a
114: .Dv SIGHUP
115: signal to
116: .Xr syslogd 8 ,
117: so this option should only be used in debugging.
1.20 aaron 118: .It Fl v
119: Be verbose.
120: In this mode it will print out each log and its
121: reasons for either trimming that log or skipping it.
1.26 millert 122: .It Fl a Ar directory
123: Specify a
124: .Ar directory
125: into which archived log files will be written.
126: If
127: .Ar directory
1.32 ! jmc 128: is a relative path, it is appended to the parent directory
1.26 millert 129: of each log and the archived log is stored in the result.
130: If an absolute path is given, all archived logs are stored in the given
131: .Ar directory .
132: If
133: .Ar directory
134: does not exist for a specified log, it is ignored for that entry and
135: the log is rotated as if the
136: .Fl a
137: option was not specified.
1.20 aaron 138: .It Fl f Ar config_file
139: Use
140: .Ar config_file
141: instead of
142: .Pa /etc/newsyslog.conf
143: for the configuration file.
1.18 aaron 144: .El
1.28 millert 145: .Pp
146: If one or more
147: .Ar log
148: files are specified on the command line, only the specified logs will
149: be rotated.
150: Note that each
151: .Ar log
152: specified must have an entry in
153: .Pa /etc/newsyslog.conf .
1.18 aaron 154: .Pp
1.32 ! jmc 155: A log can be archived because of two reasons:
1.18 aaron 156: The log file can have
1.1 deraadt 157: grown bigger than a preset size in kilobytes, or a preset number of
1.18 aaron 158: hours may have elapsed since the last log archive.
159: The granularity of
1.13 aaron 160: .Nm
1.4 downsj 161: is dependent on how often it is scheduled to run in
162: .Xr cron 8 .
163: Since the program is quite fast, it may be scheduled to run every hour
1.1 deraadt 164: without any ill effects.
1.4 downsj 165: .Pp
1.13 aaron 166: When starting up,
167: .Nm
1.1 deraadt 168: reads in a configuration file to determine which logs should be looked
1.18 aaron 169: at.
170: By default, this configuration file is
1.4 downsj 171: .Pa /etc/newsyslog.conf .
1.1 deraadt 172: Each line of the file contains information about a particular log file
173: that should be handled by
1.4 downsj 174: .Nm newsyslog .
175: Each line has five mandatory fields and up to three optional fields, with a
1.18 aaron 176: whitespace separating each field.
177: Blank lines or lines beginning with a hash mark
178: .Pq Ql #
179: are ignored.
180: The fields of the configuration file are as
1.13 aaron 181: follows:
1.4 downsj 182: .Bl -tag -width XXXXXXXXXXXXXXXX
183: .It logfile name
184: The full pathname of the system log file to be archived.
185: .It owner.group of archives (optional)
1.18 aaron 186: Specify an ownership and group for the archive file.
187: The
1.13 aaron 188: .Ql \&.
189: is essential, even if the
1.4 downsj 190: .Ar owner
1.1 deraadt 191: or
1.4 downsj 192: .Ar group
1.18 aaron 193: field is left blank.
194: The fields may be numeric, or a name which is looked up
1.4 downsj 195: in the system password and group databases.
196: .It mode of logfile & archives
197: Octal mode of created log files and archives.
198: .It number of archives
1.6 d 199: Specify the number of archives to be kept besides the log file itself.
1.4 downsj 200: .It size of archives
1.24 millert 201: When the size of the log file (in kilobytes) reaches this point, the log
202: file is trimmed as described above.
1.18 aaron 203: If this field is replaced by a
1.13 aaron 204: .Ql * ,
205: then the size of
1.4 downsj 206: the log file is not taken into account when determining when to trim the
207: log file.
1.25 millert 208: By default, files smaller than 512 bytes are not rotated unless the
1.24 millert 209: .Sq B
210: (binary) flag is set.
211: This prevents
212: .Nm
213: from rotating files consisting solely of a message indicating
214: that the log file has been turned over.
1.4 downsj 215: .It archive interval
1.18 aaron 216: Specify the time separation between the trimming of the log file.
217: If this field is replaced by a
1.13 aaron 218: .Ql * ,
219: the number of hours since the last time the
1.4 downsj 220: log was trimmed will not be taken into consideration.
221: .It flags (optional)
1.1 deraadt 222: The
1.4 downsj 223: .Ar flags
1.1 deraadt 224: field specifies if the archives should have any special processing
1.18 aaron 225: done to the archived log files.
226: The
1.13 aaron 227: .Sq Z
228: flag will make the archive
1.4 downsj 229: files compressed to save space using
230: .Xr gzip 1
231: or
232: .Xr compress 1 ,
1.18 aaron 233: depending on compilation options.
234: The
1.13 aaron 235: .Sq B
236: flag means that the file is a
1.8 aaron 237: binary file, and so the ASCII message which
1.13 aaron 238: .Nm
1.1 deraadt 239: inserts to indicate the fact that the logs have been turned over
1.18 aaron 240: should not be included.
241: The
1.13 aaron 242: .Sq M
243: flag marks this entry as a monitored
1.4 downsj 244: log file.
1.22 wcobb 245: The
246: .Sq F
247: flag specifies that symbolic links should be followed.
1.31 millert 248: .It monitor notification (only used with the `M' flag)
249: Specify the username (or email address) that should receive notification
250: messages if this is a monitored log file.
1.18 aaron 251: Notification messages are sent as email; the operator
1.13 aaron 252: deserves what they get if they mark the
1.5 downsj 253: .Xr sendmail 8
1.6 d 254: log file as monitored.
1.7 millert 255: .It pid file (optional)
1.14 aaron 256: Specify a file containing the PID of a process to send a
257: .Dv SIGHUP
258: signal to instead of
1.7 millert 259: .Pa /var/run/syslog.pid .
1.16 millert 260: .It signal (optional)
1.18 aaron 261: Specify the signal to send to the process instead of
262: .Dv SIGHUP .
263: Signal names
1.16 millert 264: must start with
265: .Dq SIG
1.18 aaron 266: and be the signal name, not the number, e.g.,
1.23 millert 267: .Dv SIGUSR1 .
1.16 millert 268: .It command (optional)
269: Specify a command to run instead of sending a signal to the process.
1.18 aaron 270: The command must be enclosed in double quotes
1.30 deraadt 271: .Pq Ql \&" .
1.29 millert 272: The empty string,
273: .Ql \&"\&" ,
274: can use used to prevent
275: .Nm
276: from sending a signal or running a command.
1.18 aaron 277: You cannot specify both a command and a PID file.
1.25 millert 278: .Em NOTE:
1.19 millert 279: If you specify a command to be run,
280: .Nm
281: will not send a
282: .Dv SIGHUP to
283: .Xr syslogd 8 .
1.4 downsj 284: .El
285: .Sh FILES
286: .Bl -tag -width /etc/newsyslog.conf
287: .It Pa /etc/newsyslog.conf
1.11 aaron 288: default configuration file
1.4 downsj 289: .El
290: .Sh SEE ALSO
1.8 aaron 291: .Xr compress 1 ,
1.4 downsj 292: .Xr gzip 1 ,
293: .Xr syslog 3 ,
1.8 aaron 294: .Xr syslogd 8
1.21 mpech 295: .Sh AUTHORS
1.18 aaron 296: .Bd -unfilled
1.1 deraadt 297: Theodore Ts'o, MIT Project Athena
298: Copyright 1987, Massachusetts Institute of Technology
1.4 downsj 299: .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