usr.sbin/newsyslog/newsyslog.8

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