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