usr.sbin/newsyslog/newsyslog.8

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