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