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.23.2.14 2003/05/07 20:42:56 gad Exp $
   5 .\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.8,v 1.2 2003/06/17 04:29:57 dillon 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 April 27, 2003
  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 CFnrsv
  30 .Op Fl R Ar tagname
  31 .Op Fl a Ar directory
  32 .Op Fl f Ar config_file
  33 .Op 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.  If a log file
  40 is determined to require archiving,
  41 .Nm
  42 rearranges the files so that
  43 .Dq Va logfile
  44 is empty,
  45 .Dq Va logfile Ns Li \&.0
  46 has
  47 the last period's logs in it,
  48 .Dq Va logfile Ns Li \&.1
  49 has the next to last
  50 period's logs in it, and so on, up to a user-specified number of
  51 archived logs.  Optionally the archived logs can be compressed to save
  52 space.
  53 .Pp
  54 A log can be archived for three reasons:
  55 .Bl -enum -offset indent
  56 .It
  57 It is larger than the configured size (in kilobytes).
  58 .It
  59 A configured number of hours have elapsed since the log was last
  60 archived.
  61 .It
  62 This is the specific configured hour for rotation of the log.
  63 .El
  64 .Pp
  65 The granularity of
  66 .Nm
  67 is dependent on how often it is scheduled to run by
  68 .Xr cron 8 .
  69 Since the program is quite fast, it may be scheduled to run every hour
  70 without any ill effects,
  71 and mode three (above) assumes that this is so.
  72 .Pp
  73 When starting up,
  74 .Nm
  75 reads in a configuration file to determine which logs may potentially
  76 be archived.
  77 By default, this configuration file is
  78 .Pa /etc/newsyslog.conf .
  79 Each line of the file contains information about a particular log file
  80 that should be handled by
  81 .Nm .
  82 Each line has five mandatory fields and four optional fields, with
  83 whitespace separating each field.  Blank lines or lines beginning with
  84 ``#'' are ignored.  If ``#'' is placed in the middle of the line,
  85 ``#'' character and the rest of the line after it is ignored.
  86 To prevent special meaning, the ``#'' may be escaped with ``\\'',
  87 in this case preceding ``\\'' is removed and ``#'' treated as ordinary
  88 character.  The fields of the configuration file are as
  89 follows:
  90 .Pp
  91 .Bl -tag -width indent
  92 .It Ar logfile_name
  93 Name of the system log file to be archived, or the literal string
  94 ``<default>''.
  95 The special default entry will be only be used if some log file
  96 name is given as a command line argument on the
  97 .Nm
  98 command, and if that log file name is not matched by any other
  99 line in the configuration file.
 100 .It Ar owner : Ns Ar group
 101 This optional field specifies the owner and group for the archive file.
 102 The ":" is essential, even if the
 103 .Ar owner
 104 or
 105 .Ar group
 106 field is left blank.  The field may be numeric, or a name which is
 107 present in
 108 .Pa /etc/passwd
 109 or
 110 .Pa /etc/group .
 111 .It Ar mode
 112 Specify the mode of the log file and archives.
 113 .It Ar count
 114 Specify the number of archive files to be kept
 115 besides the log file itself.
 116 .It Ar size
 117 When the size of the log file reaches
 118 .Ar size
 119 in kilobytes,
 120 the log file will be trimmed as described above.  If this field
 121 is replaced by an asterisk
 122 .Pq Ql \&* ,
 123 then the size of the log file is not taken into account
 124 when determining when to trim the log file.
 125 .It Ar when
 126 The
 127 .Ar when
 128 field can consist of an interval, a specific time, or both.  If
 129 the
 130 .Ar when
 131 field is an asterisk
 132 .Pq Ql \&*
 133 log rotation will depend only on the contents of the
 134 .Ar size
 135 field.
 136 Otherwise, the
 137 .Ar when
 138 field consists of an optional interval in hours, optionally followed
 139 by an
 140 .So Li \&@ Sc Ns No -sign
 141 and a time in a restricted
 142 .Tn ISO 8601
 143 format or by an
 144 .So Li \&$ Sc Ns No -sign
 145 and a time specification for logfile rotation at a fixed time once
 146 per day, per week or per month.
 147 .Pp
 148 If a time is specified, the log file will only be trimmed if
 149 .Nm
 150 is run within one hour of the specified time.  If an
 151 interval is specified, the log file will be trimmed if that many hours have
 152 passed since the last rotation.  When both a time and an interval are
 153 specified, both conditions must be satisfied for the rotation to take
 154 place.
 155 .Pp
 156 There is no provision for specification of a timezone.  There is
 157 little point in specifying an explicit minutes or seconds component in
 158 the current implementation, since the only comparison is `within the
 159 hour'.
 160 .Pp
 161 .Sy ISO 8601 restricted time format
 162 .Pp
 163 The lead-in character for a restricted
 164 .Tn ISO 8601
 165 time is
 166 an
 167 .So Li \&@ Sc Ns No -sign .
 168 The particular format of the time in restricted
 169 .Tn ISO 8601
 170 is:
 171 .Sm off
 172 .Oo
 173 .Oo
 174 .Oo
 175 .Oo
 176 .Oo
 177 .Va \&cc
 178 .Oc
 179 .Va \&yy
 180 .Oc
 181 .Va \&mm
 182 .Oc
 183 .Va \&dd
 184 .Oc
 185 .Oo
 186 .Li \&T
 187 .Oo
 188 .Va \&hh
 189 .Oo
 190 .Va \&mm
 191 .Oo
 192 .Va \&ss
 193 .Oc
 194 .Oc
 195 .Oc
 196 .Oc
 197 .Oc .
 198 .Sm on
 199 Optional date fields default to the appropriate component of the
 200 current date; optional time fields default to midnight; hence if today
 201 is January 22, 1999, the following date specifications are all
 202 equivalent:
 203 .Pp
 204 .Bl -item -compact -offset indent
 205 .It
 206 .Sq Li 19990122T000000
 207 .It
 208 .Sq Li 990122T000000
 209 .It
 210 .Sq Li 0122T000000
 211 .It
 212 .Sq Li 22T000000
 213 .It
 214 .Sq Li T000000
 215 .It
 216 .Sq Li T0000
 217 .It
 218 .Sq Li T00
 219 .It
 220 .Sq Li 22T
 221 .It
 222 .Sq Li \&T
 223 .It
 224 .Sq Li \&
 225 .El
 226 .Pp
 227 .Sy Day, week and month time format
 228 .Pp
 229 The lead-in character for day, week and month specification is a
 230 .So Li \&$ Sc Ns No -sign .
 231 The particular format of day, week and month specification is:
 232 .Op Va D\&hh ,
 233 .Op Va W\&w Ns Op Va D\&hh
 234 and
 235 .Op Va M\&dd Ns Op Va D\&hh
 236 respectively.
 237 Optional time fields default to midnight.
 238 The ranges for day and hour specifications are:
 239 .Pp
 240 .Bl -tag -width Ds -compact -offset indent
 241 .It Ar hh
 242 hours, range 0 ... 23
 243 .It Ar w
 244 day of week, range 0 ... 6, 0 = Sunday
 245 .It Ar dd
 246 day of month, range 1 ... 31, or the letter
 247 .Em L
 248 or
 249 .Em l
 250 to specify the last day of the month.
 251 .El
 252 .Pp
 253 Some examples:
 254 .Pp
 255 .Bl -tag -width Ds -compact -offset indent
 256 .It Ar $D0
 257 rotate every night at midnight
 258 (same as
 259 .Ar @T00 )
 260 .It Ar $D23
 261 rotate every day at 23:00 hr
 262 (same as
 263 .Ar @T23 )
 264 .It Ar $W0D23
 265 rotate every week on Sunday at 23:00 hr
 266 .It Ar $W5D16
 267 rotate every week on Friday at 16:00 hr
 268 .It Ar $M1D0
 269 rotate at the first day of every month at midnight
 270 (i.e., the start of the day; same as
 271 .Ar @01T00 )
 272 .It Ar $M5D6
 273 rotate on every 5th day of month at 6:00 hr
 274 (same as
 275 .Ar @05T06 )
 276 .El
 277 .Pp
 278 .It Ar flags
 279 This optional field is made up of one or more characters
 280 that specify any special processing to be done for the log
 281 files matched by this line.
 282 The following are valid flags:
 283 .Bl -tag -width indent
 284 .It Sy B
 285 indicates that the log file is a binary file, or has some
 286 special format.
 287 Usually
 288 .Nm
 289 inserts an
 290 .Tn ASCII
 291 message into a log file when rotating the file, to indicate
 292 when and sometimes why the log file was rotated.
 293 If
 294 .Sy B
 295 is specified, then that informational message will not be
 296 inserted into the log file.
 297 .It Sy C
 298 indicates that the log file should be created if it does not
 299 already exist, and if the
 300 .Fl C
 301 option was also specified on the command line.
 302 .It Sy G
 303 indicates that the specified
 304 .Ar logfile_name
 305 is a shell pattern, and that
 306 .Nm
 307 should archive all filenames matching that pattern, using the
 308 other options specified on this line.
 309 See
 310 .Xr glob 3
 311 for details on syntax and matching rules.
 312 .It Sy J
 313 indicates that
 314 .Nm
 315 should attempt to save disk space by compressing the rotated
 316 log file using
 317 .Xr bzip2 1 .
 318 .It Sy N
 319 indicates that there is no process which needs to be signalled
 320 when this log file is rotated.
 321 .It Sy U
 322 indicates that the file specified by
 323 .Ar path_to_pid_file
 324 will contain the id for a process group, instead of a process.
 325 This option also requires that the first line in that file must
 326 be a negative value, to distinguish it from a value for a
 327 process id.
 328 .It Sy W
 329 if used with the
 330 .Sy Z
 331 or
 332 .Sy J
 333 flag, this indicates that
 334 .Nm
 335 should wait for previously started compression jobs to complete before
 336 starting a new one for this entry.
 337 If this is used with the
 338 .Sy G
 339 flag, and if multiple log files match the given pattern, then
 340 .Nm
 341 will compress those logs one by one.
 342 This ensures that only one compression job is running at a time.
 343 .It Sy Z
 344 indicates that
 345 .Nm
 346 should attempt to save disk space by compressing the rotated
 347 log file using
 348 .Xr gzip 1 .
 349 .It Sy -
 350 a minus sign will not cause any special processing, but it
 351 can be used as a placeholder to create a
 352 .Ar flags
 353 field when you need to specify any of the following fields.
 354 .El
 355 .It Ar path_to_pid_file
 356 This optional field specifies the file name to read to find the daemon
 357 process id, or to find a process group id if the
 358 .Sy U
 359 flag was specified.
 360 If this field is present, a
 361 .Ar signal_number
 362 is sent the process id contained in this file.
 363 If this field is not present, then a SIGHUP signal will be
 364 sent to
 365 .Xr syslogd 8 ,
 366 unless the
 367 .Sy N
 368 flag has been specified.
 369 This field must start with "/" in order to be recognized
 370 properly.
 371 .It Ar signal_number
 372 This optional field specifies the signal number that will be sent
 373 to the daemon process (or to all processes in a process group, if
 374 the
 375 .Sy U
 376 flag was specified).
 377 If this field is not present, then a SIGHUP signal will be sent.
 378 .El
 379 .Sh OPTIONS
 380 The following options can be used with
 381 .Nm :
 382 .Bl -tag -width indent
 383 .It Fl f Ar config_file
 384 Instruct
 385 .Nm
 386 to use
 387 .Ar config_file
 388 instead of
 389 .Pa /etc/newsyslog.conf
 390 for its configuration file.
 391 .It Fl a Ar directory
 392 Specify a
 393 .Ar directory
 394 into which archived log files will be written.
 395 If a relative path is given,
 396 it is appended to the path of each log file
 397 and the resulting path is used as the directory
 398 into which the archived log for that log file will be written.
 399 If an absolute path is given,
 400 all archived logs are written into the given
 401 .Ar directory .
 402 If any component of the path
 403 .Ar directory
 404 does not exist,
 405 it will be created when
 406 .Nm
 407 is run.
 408 .It Fl v
 409 Place
 410 .Nm
 411 in verbose mode.  In this mode it will print out each log and its
 412 reasons for either trimming that log or skipping it.
 413 .It Fl n
 414 Cause
 415 .Nm
 416 not to trim the logs, but to print out what it would do if this option
 417 were not specified.
 418 .It Fl r
 419 Remove the restriction that
 420 .Nm
 421 must be running as root.  Of course,
 422 .Nm
 423 will not be able to send a HUP signal to
 424 .Xr syslogd 8
 425 so this option should only be used in debugging.
 426 .It Fl s
 427 Specify that
 428 .Nm
 429 should not send any signals to any daemon processes that it would
 430 normally signal when rotating a log file.
 431 For any log file which is rotated, this option will usually also
 432 mean the rotated log file will not be compressed if there is a
 433 daemon which would have been signalled without this option.
 434 However, this option is most likely to be useful when specified
 435 with the
 436 .Fl R
 437 option, and in that case the compression will be done.
 438 .It Fl C
 439 If specified once, then
 440 .Nm
 441 will create any log files which do not exist, and which have the
 442 .Sy C
 443 flag specified in their config file entry.
 444 If specified multiple times, then
 445 .Nm
 446 will create all log files which do not already exist.
 447 If log files are given on the command-line, then the
 448 .Fl C
 449 or
 450 .Fl CC
 451 will only apply to those specific log files.
 452 .It Fl F
 453 Force
 454 .Nm
 455 to trim the logs, even if the trim conditions have not been met.  This
 456 option is useful for diagnosing system problems by providing you with
 457 fresh logs that contain only the problems.
 458 .It Fl R Ar tagname
 459 Specify that
 460 .Nm
 461 should rotate a given list of files, even if trim conditions are not
 462 met for those files.
 463 The
 464 .Ar tagname
 465 is only used in the messages written to the log files which are
 466 rotated.
 467 This differs from the
 468 .Fl F
 469 option in that one or more log files must also be specified, so that
 470 .Nm
 471 will only operate on those specific files.
 472 This option is mainly intended for the daemons or programs which write
 473 some log files, and want to trigger a rotate based on their own criteria.
 474 With this option they can execute
 475 .Nm
 476 to trigger the rotate when they want it to happen, and still give the
 477 system administrator a way to specify the rules of rotation (such as how
 478 many backup copies are kept, and what kind of compression is done).
 479 When a daemon does execute
 480 .Nm
 481 with the
 482 .Fl R
 483 option, it should make sure all of the log files are closed before
 484 calling
 485 .Nm ,
 486 and then it should re-open the files after
 487 .Nm
 488 returns.
 489 Usually the calling process will also want to specify the
 490 .Fl s
 491 option, so
 492 .Nm
 493 will not send a signal to the very process which called it to force
 494 the rotate.
 495 Skipping the signal step will also mean that
 496 .Nm
 497 will return faster, since
 498 .Nm
 499 normally waits a few seconds after any signal that is sent.
 500 .El
 501 .Pp
 502 If additional command line arguments are given,
 503 .Nm
 504 will only examine log files that match those arguments; otherwise, it
 505 will examine all files listed in the configuration file.
 506 .Sh FILES
 507 .Bl -tag -width /etc/newsyslog.confxxxx -compact
 508 .It Pa /etc/newsyslog.conf
 509 .Nm
 510 configuration file
 511 .El
 512 .Sh BUGS
 513 Doesn't yet automatically read the logs to find security breaches.
 514 .Sh AUTHORS
 515 .An Theodore Ts'o ,
 516 MIT Project Athena
 517 .Pp
 518 Copyright 1987, Massachusetts Institute of Technology
 519 .Sh COMPATIBILITY
 520 Previous versions of the
 521 .Nm
 522 utility used the dot (``.'') character to
 523 distinguish the group name.
 524 Beginning with
 525 .Fx 3.3 ,
 526 this has been changed to a colon (``:'') character so that user and group
 527 names may contain the dot character.  The dot (``.'') character is still
 528 accepted for backwards compatibility.
 529 .Sh "SEE ALSO"
 530 .Xr gzip 1 ,
 531 .Xr syslog 3 ,
 532 .Xr chown 8 ,
 533 .Xr syslogd 8