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