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 newsyslog 28.Op Fl Fnrv 29.Op Fl f Ar config_file 30.Op Fl a Ar directory 31.Sh DESCRIPTION 32.Nm Newsyslog 33is a program that should be scheduled to run periodically by 34.Xr cron 8 . 35When it is executed it archives log files if necessary. If a log file 36is determined to require archiving, 37.Nm 38rearranges the files so that 39.Dq Va logfile 40is empty, 41.Dq Va logfile Ns Li \&.0 42has 43the last period's logs in it, 44.Dq Va logfile Ns Li \&.1 45has the next to last 46period's logs in it, and so on, up to a user-specified number of 47archived logs. Optionally the archived logs can be compressed to save 48space. 49.Pp 50A log can be archived for three reasons: 51.Bl -enum -offset indent 52.It 53It is larger than the configured size (in kilobytes). 54.It 55A configured number of hours have elapsed since the log was last 56archived. 57.It 58This is the specific configured hour for rotation of the log. 59.El 60.Pp 61The granularity of 62.Nm 63is dependent on how often it is scheduled to run by 64.Xr cron 8 . 65Since the program is quite fast, it may be scheduled to run every hour 66without any ill effects, 67and mode three (above) assumes that this is so. 68.Pp 69When starting up, 70.Nm 71reads in a configuration file to determine which logs may potentially 72be archived. 73By default, this configuration file is 74.Pa /etc/newsyslog.conf . 75Each line of the file contains information about a particular log file 76that should be handled by 77.Nm newsyslog . 78Each line has five mandatory fields and four optional fields, with a 79whitespace separating each field. Blank lines or lines beginning with 80``#'' are ignored. The fields of the configuration file are as 81follows: 82.Pp 83.Bl -tag -width indent 84.It Ar logfile_name 85Name of the system log file to be archived. 86.It Ar owner:group 87This optional field specifies the owner and group for the archive file. 88The ":" is essential, even if the 89.Ar owner 90or 91.Ar group 92field is left blank. The field may be numeric, or a name which is 93present in 94.Pa /etc/passwd 95or 96.Pa /etc/group . 97.It Ar mode 98Specify the mode of the log file and archives. 99.It Ar count 100Specify the number of archive files to be kept 101besides the log file itself. 102.It Ar size 103When the size of the log file reaches 104.Ar size 105in kilobytes, 106the log file will be trimmed as described above. If this field 107is replaced by an asterisk 108.Pq Ql \&* , 109then the size of the log file is not taken into account 110when determining when to trim the log file. 111.It Ar when 112The 113.Ar when 114field can consist of an interval, a specific time, or both. If 115the 116.Ar when 117field is an asterisk 118.Pq Ql \&* 119log rotation will depend only on the contents of the 120.Ar size 121field. 122Otherwise, the 123.Ar when 124field consists of an optional interval in hours, optionally followed 125by an 126.So Li \&@ Sc Ns No -sign 127and a time in a restricted 128.Tn ISO 8601 129format or by an 130.So Li \&$ Sc Ns No -sign 131and a time specification for logfile rotation at a fixed time once 132per day, per week or per month. 133.Pp 134If a time is specified, the log file will only be trimmed if 135.Nm 136is run within one hour of the specified time. If an 137interval is specified, the log file will be trimmed if that many hours have 138passed since the last rotation. When both a time and an interval are 139specified, both conditions must be satisfied for the rotation to take 140place. 141.Pp 142There is no provision for specification of a timezone. There is 143little point in specifying an explicit minutes or seconds component in 144the current implementation, since the only comparison is `within the 145hour'. 146.Pp 147.Em ISO 8601 restricted time format 148.Pp 149The lead-in character for a restricted 150.Tn ISO 8601 151time is 152an 153.So Li \&@ Sc Ns No -sign . 154The particular format of the time in restricted 155.Tn ISO 8601 156is: 157.Sm off 158.Oo 159.Oo 160.Oo 161.Oo 162.Oo 163.Va \&cc 164.Oc 165.Va \&yy 166.Oc 167.Va \&mm 168.Oc 169.Va \&dd 170.Oc 171.Oo 172.Li \&T 173.Oo 174.Va \&hh 175.Oo 176.Va \&mm 177.Oo 178.Va \&ss 179.Oc 180.Oc 181.Oc 182.Oc 183.Oc . 184.Sm on 185Optional date fields default to the appropriate component of the 186current date; optional time fields default to midnight; hence if today 187is January 22, 1999, the following date specifications are all 188equivalent: 189.Pp 190.Bl -item -compact -offset indent 191.It 192.Sq Li 19990122T000000 193.It 194.Sq Li 990122T000000 195.It 196.Sq Li 0122T000000 197.It 198.Sq Li 22T000000 199.It 200.Sq Li T000000 201.It 202.Sq Li T0000 203.It 204.Sq Li T00 205.It 206.Sq Li 22T 207.It 208.Sq Li \&T 209.It 210.Sq Li \& 211.El 212.Pp 213.Em Day, week and month time format 214.Pp 215The lead-in character for day, week and month specification is a 216.So Li \&$ Sc Ns No -sign . 217The particular format of day, week and month specification is: 218.Sm off 219.Oo 220.Va D\&hh 221.Oc , 222.Oo 223.Va W\&w 224.Oo 225.Va D\&hh 226.Oc 227.Oc 228and 229.Oo 230.Va M\&dd 231.Oo 232.Va D\&hh 233.Oc 234.Oc 235.Sm on 236respectively. 237Optional time fields default to midnight. 238The ranges for day and hour secifications 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.It Ar $D23 259rotate every day at 23:00 hr 260.It Ar $W0D23 261rotate every week on Sunday at 23:00 hr 262.It Ar $W5D16 263rotate every week on Friday at 16:00 hr 264.It Ar $MLD0 265rotate at the last day of every month at midnight 266.It Ar $M5D6 267rotate on every 5th day of month at 6:00 hr 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 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 Ns : 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.Sh FILES 359.Bl -tag -width /etc/newsyslog.confxxxx -compact 360.It Pa /etc/newsyslog.conf 361.Nm 362configuration file 363.El 364.Sh BUGS 365Doesn't yet automatically read the logs to find security breaches. 366.Sh AUTHORS 367.An Theodore Ts'o , 368MIT Project Athena 369.Pp 370Copyright 1987, Massachusetts Institute of Technology 371.Sh COMPATIBILITY 372Previous versions of the 373.Nm 374utility used the dot (``.'') character to 375distinguish the group name. 376Begining with 377.Fx 3.3 , 378this has been changed to a colon (``:'') character so that user and group 379names may contain the dot character. The dot (``.'') character is still 380accepted for backwards compatibility. 381.Sh "SEE ALSO" 382.Xr gzip 1 , 383.Xr syslog 3 , 384.Xr chown 8 , 385.Xr syslogd 8 386