usr.sbin/newsyslog/newsyslog.8

   1 .\" This file contains changes from the Open Software Foundation.
   2 .\"
   3 .\"     from: @(#)newsyslog.8
   4 .\" $FreeBSD$
   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 May 19, 2017
  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 a Ar directory
  30 .Op Fl d Ar directory
  31 .Op Fl f Ar config_file
  32 .Op Fl S Ar pidfile
  33 .Op Fl t Ar timefmt
  34 .Op Oo Fl R Ar tagname Oc 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
  42 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
  60 space.
  61 .Pp
  62 A log can be archived for three reasons:
  63 .Bl -enum -offset indent
  64 .It
  65 It is larger than the configured size (in kilobytes).
  66 .It
  67 A configured number of hours have elapsed since the log was last
  68 archived.
  69 .It
  70 This is the specific configured hour for rotation of the log.
  71 .El
  72 .Pp
  73 The granularity of
  74 .Nm
  75 is dependent on how often it is scheduled to run by
  76 .Xr cron 8 .
  77 Since the program is quite fast, it may be scheduled to run every hour
  78 without any ill effects,
  79 and mode three (above) assumes that this is so.
  80 .Sh OPTIONS
  81 The following options can be used with
  82 .Nm :
  83 .Bl -tag -width indent
  84 .It Fl f Ar config_file
  85 Instruct
  86 .Nm
  87 to use
  88 .Ar config_file
  89 instead of
  90 .Pa /etc/newsyslog.conf
  91 for its configuration file.
  92 .It Fl a Ar directory
  93 Specify a
  94 .Ar directory
  95 into which archived log files will be written.
  96 If a relative path is given,
  97 it is appended to the path of each log file
  98 and the resulting path is used as the directory
  99 into which the archived log for that log file will be written.
 100 If an absolute path is given,
 101 all archived logs are written into the given
 102 .Ar directory .
 103 If any component of the path
 104 .Ar directory
 105 does not exist,
 106 it will be created when
 107 .Nm
 108 is run.
 109 .It Fl d Ar directory
 110 Specify a
 111 .Ar directory
 112 which all log files will be relative to.
 113 To allow archiving of logs outside the root, the
 114 .Ar directory
 115 passed to the
 116 .Fl a
 117 option is unaffected.
 118 .It Fl v
 119 Place
 120 .Nm
 121 in verbose mode.
 122 In this mode it will print out each log and its
 123 reasons for either trimming that log or skipping it.
 124 .It Fl n
 125 Cause
 126 .Nm
 127 not to trim the logs, but to print out what it would do if this option
 128 were not specified.
 129 This option implies the
 130 .Fl r
 131 option.
 132 .It Fl r
 133 Remove the restriction that
 134 .Nm
 135 must be running as root.
 136 Of course,
 137 .Nm
 138 will not be able to send a HUP signal to
 139 .Xr syslogd 8
 140 so this option should only be used in debugging.
 141 .It Fl s
 142 Specify that
 143 .Nm
 144 should not send any signals to any daemon processes that it would
 145 normally signal when rotating a log file.
 146 For any log file which is rotated, this option will usually also
 147 mean the rotated log file will not be compressed if there is a
 148 daemon which would have been signalled without this option.
 149 However, this option is most likely to be useful when specified
 150 with the
 151 .Fl R
 152 option, and in that case the compression will be done.
 153 .It Fl t Ar timefmt
 154 If specified
 155 .Nm
 156 will create the
 157 .Dq rotated
 158 logfiles using the specified time format instead of the default
 159 sequential filenames.
 160 The filename used will be kept until it is deleted.
 161 The time format is described in the
 162 .Xr strftime 3
 163 manual page.
 164 If the
 165 .Ar timefmt
 166 argument is set to an empty string or the string
 167 .Dq DEFAULT ,
 168 the default built in time format
 169 is used.
 170 If the
 171 .Ar timefmt
 172 string is changed the old files created using the previous time format
 173 will not be automatically removed (unless the new format is very
 174 similar to the old format).
 175 This is also the case when changing from sequential filenames to time
 176 based file names, and the other way around.
 177 The time format should contain at least year, month, day, and hour to
 178 make sure rotating of old logfiles can select the correct logfiles.
 179 .It Fl C
 180 If specified once, then
 181 .Nm
 182 will create any log files which do not exist, and which have the
 183 .Sy C
 184 flag specified in their config file entry.
 185 If specified multiple times, then
 186 .Nm
 187 will create all log files which do not already exist.
 188 If log files are given on the command-line, then the
 189 .Fl C
 190 or
 191 .Fl CC
 192 will only apply to those specific log files.
 193 .It Fl F
 194 Force
 195 .Nm
 196 to trim the logs, even if the trim conditions have not been met.
 197 This
 198 option is useful for diagnosing system problems by providing you with
 199 fresh logs that contain only the problems.
 200 .It Fl N
 201 Do not perform any rotations.
 202 This option is intended to be used with the
 203 .Fl C
 204 or
 205 .Fl CC
 206 options when creating log files is the only objective.
 207 .It Fl P
 208 Prevent further action if we should send signal but the
 209 .Dq pidfile
 210 is empty or does not exist.
 211 .It Fl R Ar tagname
 212 Specify that
 213 .Nm
 214 should rotate a given list of files, even if trim conditions are not
 215 met for those files.
 216 The
 217 .Ar tagname
 218 is only used in the messages written to the log files which are
 219 rotated.
 220 This differs from the
 221 .Fl F
 222 option in that one or more log files must also be specified, so that
 223 .Nm
 224 will only operate on those specific files.
 225 This option is mainly intended for the daemons or programs which write
 226 some log files, and want to trigger a rotate based on their own criteria.
 227 With this option they can execute
 228 .Nm
 229 to trigger the rotate when they want it to happen, and still give the
 230 system administrator a way to specify the rules of rotation (such as how
 231 many backup copies are kept, and what kind of compression is done).
 232 When a daemon does execute
 233 .Nm
 234 with the
 235 .Fl R
 236 option, it should make sure all of the log files are closed before
 237 calling
 238 .Nm ,
 239 and then it should re-open the files after
 240 .Nm
 241 returns.
 242 Usually the calling process will also want to specify the
 243 .Fl s
 244 option, so
 245 .Nm
 246 will not send a signal to the very process which called it to force
 247 the rotate.
 248 Skipping the signal step will also mean that
 249 .Nm
 250 will return faster, since
 251 .Nm
 252 normally waits a few seconds after any signal that is sent.
 253 .It Fl S Ar pidfile
 254 Use
 255 .Ar pidfile
 256 as
 257 .Xr syslogd 8 Ns 's
 258 pidfile.
 259 .El
 260 .Pp
 261 If additional command line arguments are given,
 262 .Nm
 263 will only examine log files that match those arguments; otherwise, it
 264 will examine all files listed in the configuration file.
 265 .Sh FILES
 266 .Bl -tag -width /usr/local/etc/newsyslog.conf.d -compact
 267 .It Pa /etc/newsyslog.conf
 268 .Nm
 269 configuration file
 270 .It Pa /etc/newsyslog.conf.d
 271 Each file in this directory will be included by the default
 272 .Pa newsyslog.conf .
 273 .It Pa /usr/local/etc/newsyslog.conf.d
 274 Each file in this directory will be included by the default
 275 .Pa newsyslog.conf .
 276 .El
 277 .Sh COMPATIBILITY
 278 Previous versions of the
 279 .Nm
 280 utility used the dot (``.'') character to
 281 distinguish the group name.
 282 Beginning with
 283 .Fx 3.3 ,
 284 this has been changed to a colon (``:'') character so that user and group
 285 names may contain the dot character.
 286 The dot (``.'') character is still
 287 accepted for backwards compatibility.
 288 .Sh SEE ALSO
 289 .Xr bzip2 1 ,
 290 .Xr gzip 1 ,
 291 .Xr xz 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
 308 .Sh BUGS
 309 Does not yet automatically read the logs to find security breaches.