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