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 February 26, 2021 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 attempt to save disk space by compressing the rotated 312log file using 313.Xr bzip2 1 . 314.It Cm N 315indicates that there is no process which needs to be signaled 316when this log file is rotated. 317.It Cm p 318indicates that the zero-th rotated file should not be compressed. 319.It Cm R 320if this flag is set the 321.Xr newsyslog 8 322will run shell command defined in 323.Ar path_to_pid_cmd_file 324after rotation instead of trying to send signal to a process id 325stored in the file. 326.It Cm T 327if this flag is set the informational rotation message written to 328the log file will be in the format specified by RFC5424. 329Normally, the rotation message is written in the traditional (RFC3164) 330syslog format. 331.It Cm U 332indicates that the file specified by 333.Ar path_to_pid_cmd_file 334will contain the ID for a process group instead of a process. 335This option also requires that the first line in that file 336be a negative value to distinguish it from a process ID. 337.It Cm X 338indicates that 339.Xr newsyslog 8 340should attempt to save disk space by compressing the rotated 341log file using 342.Xr xz 1 . 343.It Cm Y 344indicates that 345.Xr newsyslog 8 346should attempt to save disk space by compressing the rotated 347log file using 348.Xr zstd 1 . 349.It Cm Z 350indicates that 351.Xr newsyslog 8 352should attempt to save disk space by compressing the rotated 353log file using 354.Xr gzip 1 . 355.It Fl 356a minus sign will not cause any special processing, but it 357can be used as a placeholder to create a 358.Ar flags 359field when you need to specify any of the following fields. 360.El 361.It Ar path_to_pid_cmd_file 362This optional field specifies the file name containing a daemon's 363process ID or to find a group process ID if the 364.Cm U 365flag was specified. 366If this field is present, a 367.Ar signal 368is sent to the process ID contained in this file. 369If this field is not present and the 370.Cm N 371flag has not been specified, then a 372.Dv SIGHUP 373signal will be sent to 374.Xr syslogd 8 375or to the process id found in the file specified by 376.Xr newsyslog 8 Ns 's 377.Fl S 378switch. 379This field must start with 380.Ql / 381in order to be recognized properly. 382When used with the 383.Cm R 384flag, the file is treated as a path to a binary to be executed 385by the 386.Xr newsyslog 8 387after rotation instead of sending the signal out. 388.It Ar signal 389This optional field specifies the signal that will be sent to the daemon 390process (or to all processes in a process group, if the 391.Cm U 392flag was specified). 393If this field is not present, then a 394.Dv SIGHUP 395signal will be sent. 396Signal names 397must start with 398.Dq SIG 399and be the signal name, e.g., 400.Dv SIGUSR1 . 401Alternatively, 402.Ar signal 403can be the signal number, e.g., 30 for 404.Dv SIGUSR1 . 405.El 406.Sh EXAMPLES 407The following is an example of the 408.Dq Aq Li include 409entry: 410.Dl "<include> /etc/newsyslog-local.conf" 411.Sh SEE ALSO 412.Xr bzip2 1 , 413.Xr gzip 1 , 414.Xr xz 1 , 415.Xr zstd 1 , 416.Xr syslog 3 , 417.Xr chown 8 , 418.Xr newsyslog 8 , 419.Xr syslogd 8 420.Pp 421.Rs 422.%A C. Lonvick 423.%T The BSD syslog Protocol 424.%O RFC3164 425.Re 426.Rs 427.%A R. Gerhards 428.%T The Syslog Protocol 429.%O RFC5424 430.Re 431.Sh HISTORY 432This manual page first appeared in 433.Fx 4.10 . 434