usr.sbin/newsyslog/newsyslog.8

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