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