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.6 2006/09/29 17:57:03 ru Exp $ 9.\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.conf.5,v 1.1 2007/05/12 08:52:00 swildner Exp $ 10.\" 11.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 12.\" 13.\" Permission to use, copy, modify, and distribute this software 14.\" and its documentation for any purpose and without fee is 15.\" hereby granted, provided that the above copyright notice 16.\" appear in all copies and that both that copyright notice and 17.\" this permission notice appear in supporting documentation, 18.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 19.\" used in advertising or publicity pertaining to distribution 20.\" of the software without specific, written prior permission. 21.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 22.\" the suitability of this software for any purpose. It is 23.\" provided "as is" without express or implied warranty. 24.\" 25.Dd May 2, 2007 26.Dt NEWSYSLOG.CONF 5 27.Os 28.Sh NAME 29.Nm newsyslog.conf 30.Nd 31.Xr newsyslog 8 32configuration file 33.Sh DESCRIPTION 34The 35.Nm 36file is used to set log file rotation configuration for the 37.Xr newsyslog 8 38utility. 39Configuration may designate that logs are rotated based on 40size, last rotation time, or time of day. 41The 42.Nm 43file can also be used to designate secure permissions to log 44files at rotation time. 45During initialization, 46.Xr newsyslog 8 47reads a configuration file, 48normally 49.Pa /etc/newsyslog.conf , 50to determine which logs may potentially be rotated and archived. 51Each line has five mandatory fields and four optional fields, 52separated with whitespace. 53Blank lines or lines beginning with 54.Ql # 55are ignored. 56If 57.Ql # 58is placed in the middle of the line, the 59.Ql # 60character and the rest of the line after it is ignored. 61To prevent special meaning, the 62.Ql # 63character may be escaped with 64.Ql \e\e ; 65in this case preceding 66.Ql \e\e 67is removed and 68.Ql # 69is treated as an ordinary character. 70The fields of the configuration file are as follows: 71.Bl -tag -width indent 72.It Ar logfile_name 73Name of the system log file to be archived, or the literal string 74.Dq Aq Li default . 75The special default entry will only be used if a log file 76name is given as a command line argument to 77.Xr newsyslog 8 , 78and if that log file name is not matched by any other 79line in the configuration file. 80.It Ar owner : Ns Ar group 81This optional field specifies the owner and group for the archive file. 82The 83.Ql \&: 84is essential regardless if the 85.Ar owner 86or 87.Ar group 88field is left blank or contains a value. 89The field may be numeric, or a name which is present in 90.Pa /etc/passwd 91or 92.Pa /etc/group . 93.It Ar mode 94Specify the file mode of the log file and archives. 95.It Ar count 96Specify the maximum number of archive files which may exist. 97This does not consider the current log file. 98.It Ar size 99When the size of the log file reaches 100.Ar size 101in kilobytes, the log file will be trimmed as described above. 102If this field contains an asterisk 103.Pq Ql * , 104the log file will not be trimmed based on size. 105.It Ar when 106The 107.Ar when 108field may consist of an interval, a specific time, or both. 109If the 110.Ar when 111field contains an asterisk 112.Pq Ql * , 113log rotation will solely depend on the contents of the 114.Ar size 115field. 116Otherwise, the 117.Ar when 118field consists of an optional interval in hours, usually followed 119by an 120.So Li \&@ Sc Ns No -sign 121and a time in restricted 122.Tn ISO 8601 123format. 124Additionally, the format may also be constructed with a 125.Ql $ 126sign along with a rotation time specification of once 127a day, once a week, or once a month. 128.Pp 129If a time is specified, the log file will only be trimmed if 130.Xr newsyslog 8 131is run within one hour of the specified time. 132If an interval is specified, the log file will be trimmed if that many 133hours have passed since the last rotation. 134When both a time and an interval are 135specified then both conditions must be satisfied for the rotation to 136take place. 137.Pp 138There is no provision for the specification of a timezone. 139There is little point in specifying an explicit minutes or 140seconds component in the current implementation, since the only comparison is 141.Dq within the hour . 142.Pp 143.Sy ISO 8601 restricted time format : 144.Pp 145The lead-in character for a restricted 146.Tn ISO 8601 147time is an 148.Ql @ 149sign. 150The particular format of the time in restricted 151.Tn ISO 8601 152is: 153.Sm off 154.Oo 155.Op Oo Oo Oo Va cc Oc Va yy Oc Va mm Oc Va dd 156.Oo 157.Li T 158.Op Va hh Oo Va mm Oo Va ss Oc Oc Oc 159.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 effect 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 N 292indicates that there is no process which needs to be signaled 293when this log file is rotated. 294.It Cm U 295indicates that the file specified by 296.Ar path_to_pid_file 297will contain the ID for a process group instead of a process. 298This option also requires that the first line in that file 299be a negative value to distinguish it from a process ID. 300.It Cm Z 301indicates that 302.Xr newsyslog 8 303should attempt to save disk space by compressing the rotated 304log file using 305.Xr gzip 1 . 306.It Fl 307a minus sign will not cause any special processing, but it 308can be used as a placeholder to create a 309.Ar flags 310field when you need to specify any of the following fields. 311.El 312.It Ar path_to_pid_file 313This optional field specifies the file name containing a daemon's 314process ID or to find a group process ID if the 315.Cm U 316flag was specified. 317If this field is present, a 318.Ar signal_number 319is sent the process ID contained in this file. 320If this field is not present, then a 321.Dv SIGHUP 322signal will be sent to 323.Xr syslogd 8 , 324unless the 325.Cm N 326flag has been specified. 327This field must start with 328.Ql / 329in order to be recognized properly. 330.It Ar signal_number 331This optional field specifies the signal number that will be sent 332to the daemon process (or to all processes in a process group, if the 333.Cm U 334flag was specified). 335If this field is not present, then a 336.Dv SIGHUP 337signal will be sent. 338.El 339.Sh SEE ALSO 340.Xr bzip2 1 , 341.Xr gzip 1 , 342.Xr syslog 3 , 343.Xr chown 8 , 344.Xr newsyslog 8 , 345.Xr syslogd 8 346.Sh HISTORY 347This manual page first appeared in 348.Fx 4.10 . 349