1.\" This file was split from the newsyslog(8) manual page by Tom Rhodes 2.\" and includes modifications as appropriate. 3.\" The original header is included below: 4.\" 5.\" This file contains changes from the Open Software Foundation. 6.\" 7.\" from: @(#)newsyslog.8 8.\" $FreeBSD$ 9.\" 10.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 11.\" 12.\" Permission to use, copy, modify, and distribute this software 13.\" and its documentation for any purpose and without fee is 14.\" hereby granted, provided that the above copyright notice 15.\" appear in all copies and that both that copyright notice and 16.\" this permission notice appear in supporting documentation, 17.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 18.\" used in advertising or publicity pertaining to distribution 19.\" of the software without specific, written prior permission. 20.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 21.\" the suitability of this software for any purpose. It is 22.\" provided "as is" without express or implied warranty. 23.\" 24.Dd March 10, 2004 25.Dt NEWSYSLOG.CONF 5 26.Os 27.Sh NAME 28.Nm newsyslog.conf 29.Nd configuration of the newsyslog utility 30.Sh DESCRIPTION 31The 32.Nm 33file is used to set log file rotation configuration for the 34.Xr newsyslog 8 35utility. 36Configuration may designate that logs are rotated based on 37size, last rotation time, or time of day. 38The 39.Nm 40file can also be used to designate secure permissions to log 41files at rotation time. 42During initialization, 43.Xr newsyslog 8 44reads a configuration file, 45normally 46.Pa /etc/newsyslog.conf , 47to determine which logs may potentially be rotated and archived. 48Each line has five mandatory fields and four optional fields 49separated with whitespace. 50Blank lines or lines beginning with 51.Dq # 52are ignored. 53If 54.Dq # 55is placed in the middle of the line, the 56.Dq # 57character and the rest of the line after it is ignored. 58To prevent special meaning, the 59.Dq # 60character may be escaped with 61.Dq \e\e , 62in this case preceding 63.Dq \e\e 64is removed and 65.Dq # 66treated as ordinary character. 67The fields of the configuration file are as follows: 68.Pp 69.Bl -tag -width indent 70.It Ar logfile_name 71Name of the system log file to be archived, or the literal string 72.Dq Aq default . 73The special default entry will only be used if a log file 74name is given as a command line argument to 75.Xr newsyslog 8 , 76and if that log file name is not matched by any other 77line in the configuration file. 78.It Ar owner : Ns Ar group 79This optional field specifies the owner and group for the archive file. 80The 81.Dq \&: 82is essential regardless if the 83.Ar owner 84or 85.Ar group 86field is left blank or contains a value. 87The field may be numeric, or a name which is present in 88.Pa /etc/passwd 89or 90.Pa /etc/group . 91.It Ar mode 92Specify the file mode of the log file and archives. 93.It Ar count 94Specify the maximum number of archive files which may exist. 95This does not consider the current log file. 96.It Ar size 97When the size of the log file reaches 98.Ar size 99in kilobytes, the log file will be trimmed as described above. 100If this field contains an asterisk 101.Pq Ql \&* , 102the log file will not be trimmed based on size. 103.It Ar when 104The 105.Ar when 106field may consist of an interval, a specific time, or both. 107If the 108.Ar when 109field contains an asterisk 110.Pq Ql \&* 111log rotation will solely depend on the contents of the 112.Ar size 113field. 114Otherwise, the 115.Ar when 116field consists of an optional interval in hours, usually followed 117by an 118.So Li \&@ Sc Ns No -sign 119and a time in restricted 120.Tn ISO 8601 121format. 122Additionally, the format may also be constructed with a 123.So Li \&$ Sc Ns No -sign 124along with a rotation time specification of once 125a day, once a week or once a month. 126.Pp 127If a time is specified, the log file will only be trimmed if 128.Xr newsyslog 8 129is run within one hour of the specified time. 130If an interval is specified, the log file will be trimmed if that many 131hours have passed since the last rotation. 132When both a time and an interval are 133specified then both conditions must be satisfied for the rotation to 134take place. 135.Pp 136There is no provision for the specification of a timezone. 137There is little point in specifying an explicit minutes or 138seconds component in the current implementation, since the only comparison is 139.Sq within the hour . 140.Pp 141.Sy ISO 8601 restricted time format: 142.Pp 143The lead-in character for a restricted 144.Tn ISO 8601 145time is an 146.So Li \&@ Sc Ns No -sign . 147The particular format of the time in restricted 148.Tn ISO 8601 149is: 150.Sm off 151.Oo 152.Oo 153.Oo 154.Oo 155.Oo 156.Va \&cc 157.Oc 158.Va \&yy 159.Oc 160.Va \&mm 161.Oc 162.Va \&dd 163.Oc 164.Oo 165.Li \&T 166.Oo 167.Va \&hh 168.Oo 169.Va \&mm 170.Oo 171.Va \&ss 172.Oc 173.Oc 174.Oc 175.Oc 176.Oc . 177.Sm on 178Optional date fields default to the appropriate component of the 179current date; optional time fields default to midnight; hence if today 180is January 22, 1999, the following date specifications are all 181equivalent: 182.Pp 183.Bl -item -compact -offset indent 184.It 185.Sq Li 19990122T000000 186.It 187.Sq Li 990122T000000 188.It 189.Sq Li 0122T000000 190.It 191.Sq Li 22T000000 192.It 193.Sq Li T000000 194.It 195.Sq Li T0000 196.It 197.Sq Li T00 198.It 199.Sq Li 22T 200.It 201.Sq Li \&T 202.It 203.Sq Li \& 204.El 205.Pp 206.Sy Day, week, and month time format: 207.Pp 208The lead-in character for day, week, and month specification is an 209.So Li \&$ Sc Ns No -sign . 210The particular format of day, week, and month specification is: 211.Op Va D\&hh , 212.Op Va W\&w Ns Op Va D\&hh 213and 214.Op Va M\&dd Ns Op Va D\&hh 215respectively. 216Optional time fields default to midnight. 217The ranges for day and hour specifications are: 218.Pp 219.Bl -tag -width Ds -compact -offset indent 220.It Ar hh 221hours, range 0 ... 23 222.It Ar w 223day of week, range 0 ... 6, 0 = Sunday 224.It Ar dd 225day of month, range 1 ... 31, or one of the letters 226.Em L 227or 228.Em l 229to specify the last day of the month. 230.El 231.Pp 232Some examples: 233.Pp 234.Bl -tag -width Ds -compact -offset indent 235.It Ar $D0 236rotate every night at midnight 237(same as 238.Ar @T00 ) 239.It Ar $D23 240rotate every day at 23:00 hr 241(same as 242.Ar @T23 ) 243.It Ar $W0D23 244rotate every week on Sunday at 23:00 hr 245.It Ar $W5D16 246rotate every week on Friday at 16:00 hr 247.It Ar $M1D0 248rotate at the first day of every month at midnight 249(i.e., the start of the day; same as 250.Ar @01T00 ) 251.It Ar $M5D6 252rotate on every 5th day of month at 6:00 hr 253(same as 254.Ar @05T06 ) 255.El 256.Pp 257.It Ar flags 258This optional field is made up of one or more characters 259that specify any special processing to be done for the log 260files matched by this line. 261The following are valid flags: 262.Bl -tag -width indent 263.It Sy B 264indicates that the log file is a binary file, or has some 265special format. 266Usually 267.Xr newsyslog 8 268inserts an 269.Tn ASCII 270message into a log file during rotation. 271This message is used to indicate 272when, and sometimes why the log file was rotated. 273If 274.Sy B 275is specified, then that informational message will not be 276inserted into the log file. 277.It Sy C 278indicates that the log file should be created if it does not 279already exist, and if the 280.Fl C 281option was also specified on the command line. 282.It Sy G 283indicates that the specified 284.Ar logfile_name 285is a shell pattern, and that 286.Xr newsyslog 8 287should archive all filenames matching that pattern using the 288other options on this line. 289See 290.Xr glob 3 291for details on syntax and matching rules. 292.It Sy J 293indicates that 294.Xr newsyslog 8 295should attempt to save disk space by compressing the rotated 296log file using 297.Xr bzip2 1 . 298.It Sy N 299indicates that there is no process which needs to be signaled 300when this log file is rotated. 301.It Sy U 302indicates that the file specified by 303.Ar path_to_pid_file 304will contain the id for a process group instead of a process. 305This option also requires that the first line in that file 306be a negative value to distinguish it from a process id. 307.It Sy W 308if used with the 309.Sy Z 310or 311.Sy J 312flag, this indicates that 313.Xr newsyslog 8 314should wait for previously started compression jobs to complete before 315starting a new one for this entry. 316If this is used with the 317.Sy G 318flag and if multiple log files match the given pattern, then 319.Xr newsyslog 8 320will compress those logs one by one. 321This ensures that only one compression job is running at a time. 322.It Sy Z 323indicates that 324.Xr newsyslog 8 325should attempt to save disk space by compressing the rotated 326log file using 327.Xr gzip 1 . 328.It Sy - 329a minus sign will not cause any special processing, but it 330can be used as a placeholder to create a 331.Ar flags 332field when you need to specify any of the following fields. 333.El 334.It Ar path_to_pid_file 335This optional field specifies the file name containing a daemon's 336process id or to find a group process id if the 337.Sy U 338flag was specified. 339If this field is present, a 340.Ar signal_number 341is sent the process id contained in this file. 342If this field is not present, then a 343.Dv SIGHUP 344signal will be sent to 345.Xr syslogd 8 , 346unless the 347.Sy N 348flag has been specified. 349This field must start with 350.Dq / 351in order to be recognized properly. 352.It Ar signal_number 353This optional field specifies the signal number that will be sent 354to the daemon process (or to all processes in a process group, if the 355.Sy U 356flag was specified). 357If this field is not present, then a 358.Dv SIGHUP 359signal will be sent. 360.El 361.Sh SEE ALSO 362.Xr bzip 1 , 363.Xr gzip 1 , 364.Xr syslog 3 , 365.Xr chown 8 , 366.Xr newsyslog 8 , 367.Xr syslog 8 368.Sh HISTORY 369This manual page first appeared in 370.Fx 4.10 . 371