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