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