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 4, 2000 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 Fnrv 29.Op Fl f Ar config_file 30.Op Fl a Ar directory 31.Op Ar 32.Sh DESCRIPTION 33The 34.Nm 35utility should be scheduled to run periodically by 36.Xr cron 8 . 37When it is executed it archives log files if necessary. If a log file 38is determined to require archiving, 39.Nm 40rearranges the files so that 41.Dq Va logfile 42is empty, 43.Dq Va logfile Ns Li \&.0 44has 45the last period's logs in it, 46.Dq Va logfile Ns Li \&.1 47has the next to last 48period's logs in it, and so on, up to a user-specified number of 49archived logs. Optionally the archived logs can be compressed to save 50space. 51.Pp 52A log can be archived for three reasons: 53.Bl -enum -offset indent 54.It 55It is larger than the configured size (in kilobytes). 56.It 57A configured number of hours have elapsed since the log was last 58archived. 59.It 60This is the specific configured hour for rotation of the log. 61.El 62.Pp 63The granularity of 64.Nm 65is dependent on how often it is scheduled to run by 66.Xr cron 8 . 67Since the program is quite fast, it may be scheduled to run every hour 68without any ill effects, 69and mode three (above) assumes that this is so. 70.Pp 71When starting up, 72.Nm 73reads in a configuration file to determine which logs may potentially 74be archived. 75By default, this configuration file is 76.Pa /etc/newsyslog.conf . 77Each line of the file contains information about a particular log file 78that should be handled by 79.Nm . 80Each line has five mandatory fields and four optional fields, with 81whitespace separating each field. Blank lines or lines beginning with 82``#'' are ignored. If ``#'' is placed in the middle of the line, 83``#'' character and the rest of the line after it is ignored. 84To prevent special meaning, the ``#'' may be escaped with ``\\'', 85in this case preceding ``\\'' is removed and ``#'' treated as ordinary 86character. The fields of the configuration file are as 87follows: 88.Pp 89.Bl -tag -width indent 90.It Ar logfile_name 91Name of the system log file to be archived. 92.It Ar owner : Ns Ar group 93This optional field specifies the owner and group for the archive file. 94The ":" is essential, even if the 95.Ar owner 96or 97.Ar group 98field is left blank. The field may be numeric, or a name which is 99present in 100.Pa /etc/passwd 101or 102.Pa /etc/group . 103.It Ar mode 104Specify the mode of the log file and archives. 105.It Ar count 106Specify the number of archive files to be kept 107besides the log file itself. 108.It Ar size 109When the size of the log file reaches 110.Ar size 111in kilobytes, 112the log file will be trimmed as described above. If this field 113is replaced by an asterisk 114.Pq Ql \&* , 115then the size of the log file is not taken into account 116when determining when to trim the log file. 117.It Ar when 118The 119.Ar when 120field can consist of an interval, a specific time, or both. If 121the 122.Ar when 123field is an asterisk 124.Pq Ql \&* 125log rotation will depend only on the contents of the 126.Ar size 127field. 128Otherwise, the 129.Ar when 130field consists of an optional interval in hours, optionally followed 131by an 132.So Li \&@ Sc Ns No -sign 133and a time in a restricted 134.Tn ISO 8601 135format or by an 136.So Li \&$ Sc Ns No -sign 137and a time specification for logfile rotation at a fixed time once 138per day, per week or per month. 139.Pp 140If a time is specified, the log file will only be trimmed if 141.Nm 142is run within one hour of the specified time. If an 143interval is specified, the log file will be trimmed if that many hours have 144passed since the last rotation. When both a time and an interval are 145specified, both conditions must be satisfied for the rotation to take 146place. 147.Pp 148There is no provision for specification of a timezone. There is 149little point in specifying an explicit minutes or seconds component in 150the current implementation, since the only comparison is `within the 151hour'. 152.Pp 153.Sy ISO 8601 restricted time format 154.Pp 155The lead-in character for a restricted 156.Tn ISO 8601 157time is 158an 159.So Li \&@ Sc Ns No -sign . 160The particular format of the time in restricted 161.Tn ISO 8601 162is: 163.Sm off 164.Oo 165.Oo 166.Oo 167.Oo 168.Oo 169.Va \&cc 170.Oc 171.Va \&yy 172.Oc 173.Va \&mm 174.Oc 175.Va \&dd 176.Oc 177.Oo 178.Li \&T 179.Oo 180.Va \&hh 181.Oo 182.Va \&mm 183.Oo 184.Va \&ss 185.Oc 186.Oc 187.Oc 188.Oc 189.Oc . 190.Sm on 191Optional date fields default to the appropriate component of the 192current date; optional time fields default to midnight; hence if today 193is January 22, 1999, the following date specifications are all 194equivalent: 195.Pp 196.Bl -item -compact -offset indent 197.It 198.Sq Li 19990122T000000 199.It 200.Sq Li 990122T000000 201.It 202.Sq Li 0122T000000 203.It 204.Sq Li 22T000000 205.It 206.Sq Li T000000 207.It 208.Sq Li T0000 209.It 210.Sq Li T00 211.It 212.Sq Li 22T 213.It 214.Sq Li \&T 215.It 216.Sq Li \& 217.El 218.Pp 219.Sy Day, week and month time format 220.Pp 221The lead-in character for day, week and month specification is a 222.So Li \&$ Sc Ns No -sign . 223The particular format of day, week and month specification is: 224.Op Va D\&hh , 225.Op Va W\&w Ns Op Va D\&hh 226and 227.Op Va M\&dd Ns Op Va D\&hh 228respectively. 229Optional time fields default to midnight. 230The ranges for day and hour specifications are: 231.Pp 232.Bl -tag -width Ds -compact -offset indent 233.It Ar hh 234hours, range 0 ... 23 235.It Ar w 236day of week, range 0 ... 6, 0 = Sunday 237.It Ar dd 238day of month, range 1 ... 31, or the letter 239.Em L 240or 241.Em l 242to specify the last day of the month. 243.El 244.Pp 245Some examples: 246.Pp 247.Bl -tag -width Ds -compact -offset indent 248.It Ar $D0 249rotate every night at midnight 250(same as 251.Ar @T00 ) 252.It Ar $D23 253rotate every day at 23:00 hr 254(same as 255.Ar @T23 ) 256.It Ar $W0D23 257rotate every week on Sunday at 23:00 hr 258.It Ar $W5D16 259rotate every week on Friday at 16:00 hr 260.It Ar $M1D0 261rotate at the first day of every month at midnight 262(i.e., the start of the day; same as 263.Ar @01T00 ) 264.It Ar $M5D6 265rotate on every 5th day of month at 6:00 hr 266(same as 267.Ar @05T06 ) 268.El 269.Pp 270.It Ar flags 271This optional field specifies if the archive should have any 272special processing done to the archived log files. 273The 274.Ar Z 275flag will make the archive files compress to save space by 276using 277.Xr gzip 1 . 278The 279.Ar J 280flag will make the archive files compress to save space by 281using 282.Xr bzip2 1 . 283The 284.Ar B 285flag means that the file is a binary file, and so the 286.Tn ASCII 287message which 288.Nm 289inserts to indicate the fact that the logs have been 290turned over should not be included. The 291.Ar - 292flag means nothing, but can be used as a placeholder when the 293.Ar path_to_pid_file 294field is specified. 295The 296.Ar G 297flag means that the specified 298.Ar logfile_name 299is a shell pattern, which instructs the 300.Nm 301to archive all filenames matching this pattern using the same 302options. 303See 304.Xr glob 3 305for details on syntax and matching rules. 306The 307.Ar W 308flag 309in conjunction with the 310.Ar Z 311flag or the 312.Ar J 313flag means that 314.Nm 315should wait for previously started compression jobs to complete before 316starting a new one for this entry. When it is used along with the 317.Ar G 318flag, in the case when several logfiles match the pattern and should be 319compressed, the 320.Nm 321will compress logs one by one, ensuring that only one compression job 322is running at a time. 323.It Ar path_to_pid_file 324This optional field specifies 325the file name to read to find the daemon process id. If this 326field is present, a 327.Ar signal_number 328is sent the process id contained in this 329file. This field must start with "/" in order to be recognized 330properly. 331.It Ar signal_number 332This optional field specifies 333the signal number will be sent to the daemon process. 334By default 335a SIGHUP will be sent. 336.El 337.Sh OPTIONS 338The following options can be used with 339.Nm : 340.Bl -tag -width indent 341.It Fl f Ar config_file 342Instruct 343.Nm 344to use 345.Ar config_file 346instead of 347.Pa /etc/newsyslog.conf 348for its configuration file. 349.It Fl a Ar directory 350Specify a 351.Ar directory 352into which archived log files will be written. 353If a relative path is given, 354it is appended to the path of each log file 355and the resulting path is used as the directory 356into which the archived log for that log file will be written. 357If an absolute path is given, 358all archived logs are written into the given 359.Ar directory . 360If any component of the path 361.Ar directory 362does not exist, 363it will be created when 364.Nm 365is run. 366.It Fl v 367Place 368.Nm 369in verbose mode. In this mode it will print out each log and its 370reasons for either trimming that log or skipping it. 371.It Fl n 372Cause 373.Nm 374not to trim the logs, but to print out what it would do if this option 375were not specified. 376.It Fl r 377Remove the restriction that 378.Nm 379must be running as root. Of course, 380.Nm 381will not be able to send a HUP signal to 382.Xr syslogd 8 383so this option should only be used in debugging. 384.It Fl F 385Force 386.Nm 387to trim the logs, even if the trim conditions have not been met. This 388option is useful for diagnosing system problems by providing you with 389fresh logs that contain only the problems. 390.El 391.Pp 392If additional command line arguments are given, 393.Nm 394will only examine log files that match those arguments; otherwise, it 395will examine all files listed in the configuration file. 396.Sh FILES 397.Bl -tag -width /etc/newsyslog.confxxxx -compact 398.It Pa /etc/newsyslog.conf 399.Nm 400configuration file 401.El 402.Sh BUGS 403Doesn't yet automatically read the logs to find security breaches. 404.Sh AUTHORS 405.An Theodore Ts'o , 406MIT Project Athena 407.Pp 408Copyright 1987, Massachusetts Institute of Technology 409.Sh COMPATIBILITY 410Previous versions of the 411.Nm 412utility used the dot (``.'') character to 413distinguish the group name. 414Beginning with 415.Fx 3.3 , 416this has been changed to a colon (``:'') character so that user and group 417names may contain the dot character. The dot (``.'') character is still 418accepted for backwards compatibility. 419.Sh "SEE ALSO" 420.Xr gzip 1 , 421.Xr syslog 3 , 422.Xr chown 8 , 423.Xr syslogd 8 424