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