| blob | f1ddaa06326d5db8e72f70c6966dfd7088d5272e |
1 .\" This file contains changes from the Open Software Foundation.
2 .\"
3 .\" from: @(#)newsyslog.8
4 .\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.8,v 1.51 2005/06/14 12:26:35 ru Exp $
5 .\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.8,v 1.4 2007/05/12 08:52:00 swildner Exp $
6 .\"
7 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
8 .\"
9 .\" Permission to use, copy, modify, and distribute this software
10 .\" and its documentation for any purpose and without fee is
11 .\" hereby granted, provided that the above copyright notice
12 .\" appear in all copies and that both that copyright notice and
13 .\" this permission notice appear in supporting documentation,
14 .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
15 .\" used in advertising or publicity pertaining to distribution
16 .\" of the software without specific, written prior permission.
17 .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
18 .\" the suitability of this software for any purpose. It is
19 .\" provided "as is" without express or implied warranty.
20 .\"
21 .Dd May 2, 2007
22 .Dt NEWSYSLOG 8
23 .Os
24 .Sh NAME
25 .Nm newsyslog
26 .Nd maintain system log files to manageable sizes
27 .Sh SYNOPSIS
28 .Nm
29 .Op Fl CFNnrsv
30 .Op Fl R Ar tagname
31 .Op Fl a Ar directory
32 .Op Fl d Ar directory
33 .Op Fl f Ar config_file
34 .Op Ar
35 .Sh DESCRIPTION
36 The
37 .Nm
38 utility should be scheduled to run periodically by
39 .Xr cron 8 .
40 When it is executed it archives log files if necessary.
41 If a log file is determined to require archiving,
42 .Nm
43 rearranges the files so that
44 .Dq Va logfile
45 is empty,
46 .Dq Va logfile Ns Li \&.0
47 has
48 the last period's logs in it,
49 .Dq Va logfile Ns Li \&.1
50 has the next to last
51 period's logs in it, and so on, up to a user-specified number of
52 archived logs.
53 Optionally the archived logs can be compressed to save space.
54 .Pp
55 A log can be archived for three reasons:
56 .Bl -enum -offset indent
57 .It
58 It is larger than the configured size (in kilobytes).
59 .It
60 A configured number of hours have elapsed since the log was last
61 archived.
62 .It
63 This is the specific configured hour for rotation of the log.
64 .El
65 .Pp
66 The granularity of
67 .Nm
68 is dependent on how often it is scheduled to run by
69 .Xr cron 8 .
70 Since the program is quite fast, it may be scheduled to run every hour
71 without any ill effects,
72 and mode three (above) assumes that this is so.
73 .Sh OPTIONS
74 The following options can be used with
75 .Nm :
76 .Bl -tag -width indent
77 .It Fl f Ar config_file
78 Instruct
79 .Nm
80 to use
81 .Ar config_file
82 instead of
83 .Pa /etc/newsyslog.conf
84 for its configuration file.
85 .It Fl a Ar directory
86 Specify a
87 .Ar directory
88 into which archived log files will be written.
89 If a relative path is given,
90 it is appended to the path of each log file
91 and the resulting path is used as the directory
92 into which the archived log for that log file will be written.
93 If an absolute path is given,
94 all archived logs are written into the given
95 .Ar directory .
96 If any component of the path
97 .Ar directory
98 does not exist,
99 it will be created when
100 .Nm
101 is run.
102 .It Fl d Ar directory
103 Specify a
104 .Ar directory
105 which all log files will be relative to.
106 To allow archiving of logs outside the root, the
107 .Ar directory
108 passed to the
109 .Fl a
110 option is unaffected.
111 .It Fl v
112 Place
113 .Nm
114 in verbose mode.
115 In this mode it will print out each log and its
116 reasons for either trimming that log or skipping it.
117 .It Fl n
118 Cause
119 .Nm
120 not to trim the logs, but to print out what it would do if this option
121 were not specified.
122 .It Fl r
123 Remove the restriction that
124 .Nm
125 must be running as root.
126 Of course,
127 .Nm
128 will not be able to send a HUP signal to
129 .Xr syslogd 8
130 so this option should only be used in debugging.
131 .It Fl s
132 Specify that
133 .Nm
134 should not send any signals to any daemon processes that it would
135 normally signal when rotating a log file.
136 For any log file which is rotated, this option will usually also
137 mean the rotated log file will not be compressed if there is a
138 daemon which would have been signalled without this option.
139 However, this option is most likely to be useful when specified
140 with the
141 .Fl R
142 option, and in that case the compression will be done.
143 .It Fl C
144 If specified once, then
145 .Nm
146 will create any log files which do not exist, and which have the
147 .Sy C
148 flag specified in their config file entry.
149 If specified multiple times, then
150 .Nm
151 will create all log files which do not already exist.
152 If log files are given on the command-line, then the
153 .Fl C
154 or
155 .Fl CC
156 will only apply to those specific log files.
157 .It Fl F
158 Force
159 .Nm
160 to trim the logs, even if the trim conditions have not been met.
161 This option is useful for diagnosing system problems by providing you with
162 fresh logs that contain only the problems.
163 .It Fl N
164 Do not perform any rotations.
165 This option is intended to be used with the
166 .Fl C
167 or
168 .Fl CC
169 options when creating log files is the only objective.
170 .It Fl R Ar tagname
171 Specify that
172 .Nm
173 should rotate a given list of files, even if trim conditions are not
174 met for those files.
175 The
176 .Ar tagname
177 is only used in the messages written to the log files which are
178 rotated.
179 This differs from the
180 .Fl F
181 option in that one or more log files must also be specified, so that
182 .Nm
183 will only operate on those specific files.
184 This option is mainly intended for the daemons or programs which write
185 some log files, and want to trigger a rotate based on their own criteria.
186 With this option they can execute
187 .Nm
188 to trigger the rotate when they want it to happen, and still give the
189 system administrator a way to specify the rules of rotation (such as how
190 many backup copies are kept, and what kind of compression is done).
191 When a daemon does execute
192 .Nm
193 with the
194 .Fl R
195 option, it should make sure all of the log files are closed before
196 calling
197 .Nm ,
198 and then it should re-open the files after
199 .Nm
200 returns.
201 Usually the calling process will also want to specify the
202 .Fl s
203 option, so
204 .Nm
205 will not send a signal to the very process which called it to force
206 the rotate.
207 Skipping the signal step will also mean that
208 .Nm
209 will return faster, since
210 .Nm
211 normally waits a few seconds after any signal that is sent.
212 .El
213 .Pp
214 If additional command line arguments are given,
215 .Nm
216 will only examine log files that match those arguments; otherwise, it
217 will examine all files listed in the configuration file.
218 .Sh FILES
219 .Bl -tag -width /etc/newsyslog.confxxxx -compact
220 .It Pa /etc/newsyslog.conf
221 .Nm
222 configuration file
223 .El
224 .Sh COMPATIBILITY
225 Previous versions of the
226 .Nm
227 utility used the dot (``.'') character to
228 distinguish the group name.
229 Beginning with
230 .Fx 3.3 ,
231 this has been changed to a colon (``:'') character so that user and group
232 names may contain the dot character.
233 The dot (``.'') character is still accepted for backwards compatibility.
234 .Sh "SEE ALSO"
235 .Xr bzip2 1 ,
236 .Xr gzip 1 ,
237 .Xr syslog 3 ,
238 .Xr newsyslog.conf 5 ,
239 .Xr chown 8 ,
240 .Xr syslogd 8
241 .Sh HISTORY
242 The
243 .Nm
244 utility originated from
245 .Nx
246 and first appeared in
247 .Fx 2.2 .
248 .Sh AUTHORS
249 .An Theodore Ts'o ,
250 MIT Project Athena
251 .Pp
252 Copyright 1987, Massachusetts Institute of Technology
253 .Sh BUGS
254 Does not yet automatically read the logs to find security breaches.