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