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. The fields of the configuration file are as 83follows: 84.Pp 85.Bl -tag -width indent 86.It Ar logfile_name 87Name of the system log file to be archived. 88.It Ar owner : Ns Ar group 89This optional field specifies the owner and group for the archive file. 90The ":" is essential, even if the 91.Ar owner 92or 93.Ar group 94field is left blank. The field may be numeric, or a name which is 95present in 96.Pa /etc/passwd 97or 98.Pa /etc/group . 99.It Ar mode 100Specify the mode of the log file and archives. 101.It Ar count 102Specify the number of archive files to be kept 103besides the log file itself. 104.It Ar size 105When the size of the log file reaches 106.Ar size 107in kilobytes, 108the log file will be trimmed as described above. If this field 109is replaced by an asterisk 110.Pq Ql \&* , 111then the size of the log file is not taken into account 112when determining when to trim the log file. 113.It Ar when 114The 115.Ar when 116field can consist of an interval, a specific time, or both. If 117the 118.Ar when 119field is an asterisk 120.Pq Ql \&* 121log rotation will depend only on the contents of the 122.Ar size 123field. 124Otherwise, the 125.Ar when 126field consists of an optional interval in hours, optionally followed 127by an 128.So Li \&@ Sc Ns No -sign 129and a time in a restricted 130.Tn ISO 8601 131format or by an 132.So Li \&$ Sc Ns No -sign 133and a time specification for logfile rotation at a fixed time once 134per day, per week or per month. 135.Pp 136If a time is specified, the log file will only be trimmed if 137.Nm 138is run within one hour of the specified time. If an 139interval is specified, the log file will be trimmed if that many hours have 140passed since the last rotation. When both a time and an interval are 141specified, both conditions must be satisfied for the rotation to take 142place. 143.Pp 144There is no provision for specification of a timezone. There is 145little point in specifying an explicit minutes or seconds component in 146the current implementation, since the only comparison is `within the 147hour'. 148.Pp 149.Sy ISO 8601 restricted time format 150.Pp 151The lead-in character for a restricted 152.Tn ISO 8601 153time is 154an 155.So Li \&@ Sc Ns No -sign . 156The particular format of the time in restricted 157.Tn ISO 8601 158is: 159.Sm off 160.Oo 161.Oo 162.Oo 163.Oo 164.Oo 165.Va \&cc 166.Oc 167.Va \&yy 168.Oc 169.Va \&mm 170.Oc 171.Va \&dd 172.Oc 173.Oo 174.Li \&T 175.Oo 176.Va \&hh 177.Oo 178.Va \&mm 179.Oo 180.Va \&ss 181.Oc 182.Oc 183.Oc 184.Oc 185.Oc . 186.Sm on 187Optional date fields default to the appropriate component of the 188current date; optional time fields default to midnight; hence if today 189is January 22, 1999, the following date specifications are all 190equivalent: 191.Pp 192.Bl -item -compact -offset indent 193.It 194.Sq Li 19990122T000000 195.It 196.Sq Li 990122T000000 197.It 198.Sq Li 0122T000000 199.It 200.Sq Li 22T000000 201.It 202.Sq Li T000000 203.It 204.Sq Li T0000 205.It 206.Sq Li T00 207.It 208.Sq Li 22T 209.It 210.Sq Li \&T 211.It 212.Sq Li \& 213.El 214.Pp 215.Sy Day, week and month time format 216.Pp 217The lead-in character for day, week and month specification is a 218.So Li \&$ Sc Ns No -sign . 219The particular format of day, week and month specification is: 220.Op Va D\&hh , 221.Op Va W\&w Ns Op Va D\&hh 222and 223.Op Va M\&dd Ns Op Va D\&hh 224respectively. 225Optional time fields default to midnight. 226The ranges for day and hour secifications are: 227.Pp 228.Bl -tag -width Ds -compact -offset indent 229.It Ar hh 230hours, range 0 ... 23 231.It Ar w 232day of week, range 0 ... 6, 0 = Sunday 233.It Ar dd 234day of month, range 1 ... 31, or the letter 235.Em L 236or 237.Em l 238to specify the last day of the month. 239.El 240.Pp 241Some examples: 242.Pp 243.Bl -tag -width Ds -compact -offset indent 244.It Ar $D0 245rotate every night at midnight 246(same as 247.Ar @T00 ) 248.It Ar $D23 249rotate every day at 23:00 hr 250(same as 251.Ar @T23 ) 252.It Ar $W0D23 253rotate every week on Sunday at 23:00 hr 254.It Ar $W5D16 255rotate every week on Friday at 16:00 hr 256.It Ar $M1D0 257rotate at the first day of every month at midnight 258(i.e., the start of the day; same as 259.Ar @01T00 ) 260.It Ar $M5D6 261rotate on every 5th day of month at 6:00 hr 262(same as 263.Ar @05T06 ) 264.El 265.Pp 266.It Ar flags 267This optional field specifies if the archive should have any 268special processing done to the archived log files. 269The 270.Ar Z 271flag will make the archive files compress to save space by 272using 273.Xr gzip 1 . 274The 275.Ar J 276flag will make the archive files compress to save space by 277using 278.Xr bzip2 1 . 279The 280.Ar B 281flag means that the file is a binary file, and so the 282.Tn ASCII 283message which 284.Nm 285inserts to indicate the fact that the logs have been 286turned over should not be included. The 287.Ar - 288flag means nothing, but can be used as a placeholder when the 289.Ar path_to_pid_file 290field is specified. 291.It Ar path_to_pid_file 292This optional field specifies 293the file name to read to find the daemon process id. If this 294field is present, a 295.Ar signal_number 296is sent the process id contained in this 297file. This field must start with "/" in order to be recognized 298properly. 299.It Ar signal_number 300This optional field specifies 301the signal number will be sent to the daemon process. 302By default 303a SIGHUP will be sent. 304.El 305.Sh OPTIONS 306The following options can be used with 307.Nm : 308.Bl -tag -width indent 309.It Fl f Ar config_file 310Instruct 311.Nm 312to use 313.Ar config_file 314instead of 315.Pa /etc/newsyslog.conf 316for its configuration file. 317.It Fl a Ar directory 318Specify a 319.Ar directory 320into which archived log files will be written. 321If a relative path is given, 322it is appended to the path of each log file 323and the resulting path is used as the directory 324into which the archived log for that log file will be written. 325If an absolute path is given, 326all archived logs are written into the given 327.Ar directory . 328If any component of the path 329.Ar directory 330does not exist, 331it will be created when 332.Nm 333is run. 334.It Fl v 335Place 336.Nm 337in verbose mode. In this mode it will print out each log and its 338reasons for either trimming that log or skipping it. 339.It Fl n 340Cause 341.Nm 342not to trim the logs, but to print out what it would do if this option 343were not specified. 344.It Fl r 345Remove the restriction that 346.Nm 347must be running as root. Of course, 348.Nm 349will not be able to send a HUP signal to 350.Xr syslogd 8 351so this option should only be used in debugging. 352.It Fl F 353Force 354.Nm 355to trim the logs, even if the trim conditions have not been met. This 356option is useful for diagnosing system problems by providing you with 357fresh logs that contain only the problems. 358.El 359.Pp 360If additional command line arguments are given, 361.Nm 362will only examine log files that match those arguments; otherwise, it 363will examine all files listed in the configuration file. 364.Sh FILES 365.Bl -tag -width /etc/newsyslog.confxxxx -compact 366.It Pa /etc/newsyslog.conf 367.Nm 368configuration file 369.El 370.Sh BUGS 371Doesn't yet automatically read the logs to find security breaches. 372.Sh AUTHORS 373.An Theodore Ts'o , 374MIT Project Athena 375.Pp 376Copyright 1987, Massachusetts Institute of Technology 377.Sh COMPATIBILITY 378Previous versions of the 379.Nm 380utility used the dot (``.'') character to 381distinguish the group name. 382Begining with 383.Fx 3.3 , 384this has been changed to a colon (``:'') character so that user and group 385names may contain the dot character. The dot (``.'') character is still 386accepted for backwards compatibility. 387.Sh "SEE ALSO" 388.Xr gzip 1 , 389.Xr syslog 3 , 390.Xr chown 8 , 391.Xr syslogd 8 392