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.It Ar $D23 246rotate every day at 23:00 hr 247.It Ar $W0D23 248rotate every week on Sunday at 23:00 hr 249.It Ar $W5D16 250rotate every week on Friday at 16:00 hr 251.It Ar $MLD0 252rotate at the last day of every month at midnight 253.It Ar $M5D6 254rotate on every 5th day of month at 6:00 hr 255.El 256.Pp 257.It Ar flags 258This optional field specifies if the archive should have any 259special processing done to the archived log files. 260The 261.Ar Z 262flag will make the archive files compress to save space by 263using 264.Xr gzip 1 . 265The 266.Ar B 267flag means that the file is a binary file, and so the 268.Tn ASCII 269message which 270.Nm 271inserts to indicate the fact that the logs have been 272turned over should not be included. The 273.Ar - 274flag means nothing, but can be used as a placeholder when the 275.Ar path_to_pid_file 276field is specified. 277.It Ar path_to_pid_file 278This optional field specifies 279the file name to read to find the daemon process id. If this 280field is present, a 281.Ar signal_number 282is sent the process id contained in this 283file. This field must start with "/" in order to be recognized 284properly. 285.It Ar signal_number 286This optional field specifies 287the signal number will be sent to the daemon process. 288By default 289a SIGHUP will be sent. 290.El 291.Sh OPTIONS 292The following options can be used with 293.Nm : 294.Bl -tag -width indent 295.It Fl f Ar config_file 296Instruct 297.Nm 298to use 299.Ar config_file 300instead of 301.Pa /etc/newsyslog.conf 302for its configuration file. 303.It Fl a Ar directory 304Specify a 305.Ar directory 306into which archived log files will be written. 307If a relative path is given, 308it is appended to the path of each log file 309and the resulting path is used as the directory 310into which the archived log for that log file will be written. 311If an absolute path is given, 312all archived logs are written into the given 313.Ar directory . 314If any component of the path 315.Ar directory 316does not exist, 317it will be created when 318.Nm 319is run. 320.It Fl v 321Place 322.Nm 323in verbose mode. In this mode it will print out each log and its 324reasons for either trimming that log or skipping it. 325.It Fl n 326Cause 327.Nm 328not to trim the logs, but to print out what it would do if this option 329were not specified. 330.It Fl r 331Remove the restriction that 332.Nm 333must be running as root. Of course, 334.Nm 335will not be able to send a HUP signal to 336.Xr syslogd 8 337so this option should only be used in debugging. 338.It Fl F 339Force 340.Nm 341to trim the logs, even if the trim conditions have not been met. This 342option is useful for diagnosing system problems by providing you with 343fresh logs that contain only the problems. 344.El 345.Pp 346If additional command line arguments are given, 347.Nm 348will only examine log files that match those arguments; otherwise, it 349will examine all files listed in the configuration file. 350.Sh FILES 351.Bl -tag -width /etc/newsyslog.confxxxx -compact 352.It Pa /etc/newsyslog.conf 353.Nm 354configuration file 355.El 356.Sh BUGS 357Doesn't yet automatically read the logs to find security breaches. 358.Sh AUTHORS 359.An Theodore Ts'o , 360MIT Project Athena 361.Pp 362Copyright 1987, Massachusetts Institute of Technology 363.Sh COMPATIBILITY 364Previous versions of the 365.Nm 366utility used the dot (``.'') character to 367distinguish the group name. 368Begining with 369.Fx 3.3 , 370this has been changed to a colon (``:'') character so that user and group 371names may contain the dot character. The dot (``.'') character is still 372accepted for backwards compatibility. 373.Sh "SEE ALSO" 374.Xr gzip 1 , 375.Xr syslog 3 , 376.Xr chown 8 , 377.Xr syslogd 8 378