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