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 Oo Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd Oc 159.Oo Li T Oo Va hh Oo Va mm Oo Va ss Oc Oc Oc Oc Oc . 160.Sm on 161Optional date fields default to the appropriate component of the 162current date; optional time fields default to midnight; hence if today 163is January 22, 1999, the following date specifications are all 164equivalent: 165.Pp 166.Bl -item -compact -offset indent 167.It 168.Sq Li 19990122T000000 169.It 170.Sq Li 990122T000000 171.It 172.Sq Li 0122T000000 173.It 174.Sq Li 22T000000 175.It 176.Sq Li T000000 177.It 178.Sq Li T0000 179.It 180.Sq Li T00 181.It 182.Sq Li 22T 183.It 184.Sq Li T 185.It 186.Sq Li \& 187.El 188.Pp 189.Sy Day, week, and month time format: 190.Pp 191The lead-in character for day, week, and month specification is a 192.Ql $ 193sign. 194The particular format of day, week, and month specification is: 195.Op Li D Ns Va hh , 196.Op Li W Ns Va w Ns Op Li D Ns Va hh , 197and 198.Op Li M Ns Va dd Ns Op Li D Ns Va hh , 199respectively. 200Optional time fields default to midnight. 201The ranges for day and hour specifications are: 202.Pp 203.Bl -tag -width indent -offset indent -compact 204.It Ar hh 205hours, range 0..23 206.It Ar w 207day of week, range 0..6, 0 = Sunday 208.It Ar dd 209day of month, range 1..31, or one of the letters 210.Ql L 211or 212.Ql l 213to specify the last day of the month. 214.El 215.Pp 216Some examples: 217.Pp 218.Bl -tag -width indent -offset indent -compact 219.It Li $D0 220rotate every night at midnight 221(same as 222.Li @T00 ) 223.It Li $D23 224rotate every day at 23:00 225(same as 226.Li @T23 ) 227.It Li $W0D23 228rotate every week on Sunday at 23:00 229.It Li $W5D16 230rotate every week on Friday at 16:00 231.It Li $M1D0 232rotate at the first day of every month at midnight 233(i.e., the start of the day; same as 234.Li @01T00 ) 235.It Li $M5D6 236rotate on every 5th day of month at 6:00 237(same as 238.Li @05T06 ) 239.El 240.It Ar flags 241This optional field is made up of one or more characters 242that specify any special processing to be done for the log 243files matched by this line. 244The following are valid flags: 245.Bl -tag -width indent 246.It Cm B 247indicates that the log file is a binary file, or has some 248special format. 249Usually 250.Xr newsyslog 8 251inserts an 252.Tn ASCII 253message into a log file during rotation. 254This message is used to indicate 255when, and sometimes why the log file was rotated. 256If 257.Cm B 258is specified, then that informational message will not be 259inserted into the log file. 260.It Cm C 261indicates that the log file should be created if it does not 262already exist, and if the 263.Fl C 264option was also specified on the command line. 265.It Cm D 266indicates that 267.Xr newsyslog 8 268should set the 269.Dv UF_NODUMP 270flag when creating a new version of 271this log file. 272This option would affect how the 273.Xr dump 8 274command treats the log file when making a file system backup. 275.It Cm G 276indicates that the specified 277.Ar logfile_name 278is a shell pattern, and that 279.Xr newsyslog 8 280should archive all filenames matching that pattern using the 281other options on this line. 282See 283.Xr glob 3 284for details on syntax and matching rules. 285.It Cm J 286indicates that 287.Xr newsyslog 8 288should attempt to save disk space by compressing the rotated 289log file using 290.Xr bzip2 1 . 291.It Cm X 292indicates that 293.Xr newsyslog 8 294should attempt to save disk space by compressing the rotated 295log file using 296.Xr xz 1 . 297.It Cm N 298indicates that there is no process which needs to be signaled 299when this log file is rotated. 300.It Cm U 301indicates that the file specified by 302.Ar path_to_pid_file 303will contain the ID for a process group instead of a process. 304This option also requires that the first line in that file 305be a negative value to distinguish it from a process ID. 306.It Cm Z 307indicates that 308.Xr newsyslog 8 309should attempt to save disk space by compressing the rotated 310log file using 311.Xr gzip 1 . 312.It Fl 313a minus sign will not cause any special processing, but it 314can be used as a placeholder to create a 315.Ar flags 316field when you need to specify any of the following fields. 317.El 318.It Ar path_to_pid_file 319This optional field specifies the file name containing a daemon's 320process ID or to find a group process ID if the 321.Cm U 322flag was specified. 323If this field is present, a 324.Ar signal_number 325is sent to the process ID contained in this file. 326If this field is not present and the 327.Cm N 328flag has not been specified, then a 329.Dv SIGHUP 330signal will be sent to 331.Xr syslogd 8 332or to the process id found in the file specified by 333.Xr newsyslog 8 Ns 's 334.Fl S 335switch. 336This field must start with 337.Ql / 338in order to be recognized properly. 339.It Ar signal_number 340This optional field specifies the signal number that will be sent 341to the daemon process (or to all processes in a process group, if the 342.Cm U 343flag was specified). 344If this field is not present, then a 345.Dv SIGHUP 346signal will be sent. 347.El 348.Sh SEE ALSO 349.Xr bzip2 1 , 350.Xr gzip 1 , 351.Xr xz 1 , 352.Xr syslog 3 , 353.Xr chown 8 , 354.Xr newsyslog 8 , 355.Xr syslogd 8 356.Sh HISTORY 357This manual page first appeared in 358.Fx 4.10 . 359