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