1.\" $OpenBSD: newsyslog.8,v 1.56 2024/10/30 09:16:24 jan Exp $ 2.\" 3.\" Copyright (c) 1997, Jason Downs. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS 15.\" OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 16.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 17.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, 18.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 19.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 20.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 21.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" This file contains changes from the Open Software Foundation. 27.\" 28.\" from: @(#)newsyslog.8 29.\" 30.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 31.\" 32.\" Permission to use, copy, modify, and distribute this software 33.\" and its documentation for any purpose and without fee is 34.\" hereby granted, provided that the above copyright notice 35.\" appear in all copies and that both that copyright notice and 36.\" this permission notice appear in supporting documentation, 37.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 38.\" used in advertising or publicity pertaining to distribution 39.\" of the software without specific, written prior permission. 40.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 41.\" the suitability of this software for any purpose. It is 42.\" provided "as is" without express or implied warranty. 43.\" 44.Dd $Mdocdate: October 30 2024 $ 45.Dt NEWSYSLOG 8 46.Os 47.Sh NAME 48.Nm newsyslog , 49.Nm newsyslog.conf 50.Nd rotate log files 51.Sh SYNOPSIS 52.Nm newsyslog 53.Op Fl Fmnrv 54.Op Fl a Ar directory 55.Op Fl f Ar config_file 56.Op Ar log ... 57.Sh DESCRIPTION 58The 59.Nm 60utility rotates log files when they exceed a configurable size or age. 61The 62.Ar log 63file is renamed to 64.Pa log.0 65and an empty file is created in its place. 66An archive of older logs may be kept: 67in order of increasing age, these files are named 68.Pa log.1 , 69.Pa log.2 , 70and so on. 71When their number exceeds a given limit, the oldest is removed. 72The archived logs may also be compressed. 73.Pp 74The options are as follows: 75.Bl -tag -width Ds 76.It Fl a Ar directory 77Specify a 78.Ar directory 79into which archived log files will be written. 80If 81.Ar directory 82is a relative path, it is appended to the parent directory 83of each log and the archived log is stored in the result. 84If an absolute path is given, all archived logs are stored in the given 85.Ar directory . 86If 87.Ar directory 88does not exist for a specified log, it is ignored for that entry and 89the log is rotated as if the 90.Fl a 91option was not specified. 92.It Fl F 93Force 94.Nm 95to trim logs regardless of the size and/or age requirements specified in 96.Pa /etc/newsyslog.conf . 97This option may be combined with the 98.Fl n 99or 100.Fl v 101flags to aid in debugging problems with 102.Pa /etc/newsyslog.conf . 103.It Fl f Ar config_file 104Use 105.Ar config_file 106instead of 107.Pa /etc/newsyslog.conf 108for the configuration file. 109.It Fl m 110Monitoring mode; only entries marked with an 111.Sq M 112in flags are processed. 113For each log file being monitored, any log output since the last time 114.Nm 115was run with the 116.Fl m 117flag is mailed to the user listed in the monitor notification section. 118.It Fl n 119Do not trim the logs, but instead print out what would be done if this option 120were not specified. 121.It Fl r 122Removes the restriction that 123.Nm 124must be running as root. 125Note that in this mode 126.Nm 127will not be able to send a 128.Dv SIGHUP 129signal to 130.Xr syslogd 8 . 131.It Fl v 132Place 133.Nm newsyslog 134in verbose mode. 135In this mode it will print out each log and its 136reasons for either trimming that log or skipping it. 137.El 138.Pp 139In the default system configuration, 140.Nm 141is run by 142.Xr cron 8 , 143but it may also be run manually. 144If one or more 145.Ar log 146files are specified on the command line, only the specified files are 147rotated. 148Note that each 149.Ar log 150specified must have an entry in 151.Pa /etc/newsyslog.conf . 152.Pp 153A log can be archived because of two reasons: 154The log file can have 155grown bigger than a preset size in kilobytes, or a preset number of 156hours may have elapsed since the last log archive. 157The granularity of 158.Nm 159is dependent on how often it is scheduled to run in 160.Xr cron 8 . 161Since the program is quite fast, it may be scheduled to run every hour 162without any ill effects. 163.Pp 164When starting up, 165.Nm 166reads in a configuration file to determine which logs should be looked 167at. 168By default, this configuration file is 169.Pa /etc/newsyslog.conf . 170Each line of the file contains information about a particular log file 171that should be handled by 172.Nm newsyslog . 173Each line has five mandatory fields and up to three optional fields, with 174whitespace separating each field. 175Blank lines or lines beginning with a hash mark 176.Pq Ql # 177are ignored. 178The fields of the configuration file are as 179follows: 180.Bl -tag -width XXXXXXXXXXXXXXXX 181.It Ar logfile_name 182The full pathname of the system log file to be archived. 183.It Ar owner:group 184This optional field specifies the owner and group for the archive file. 185The 186.Ql \&: 187is essential, even if the 188.Ar owner 189or 190.Ar group 191field is left blank. 192The fields may be numeric, or a name which is looked up 193in the system password and group databases. 194For backwards compatibility, a 195.Ql \&. 196may be used instead of a 197.Ql \&: . 198If either 199.Ar owner 200or 201.Ar group 202is not specified, the owner and/or group of the existing log file is used. 203.It Ar mode 204File mode (in octal) to use for created log files and archives. 205.It Ar count 206The number of archives to be kept besides the log file itself. 207.It Ar size 208When the size of the log file (in kilobytes) reaches this point, the log 209file is trimmed as described above. 210If this field is replaced by an 211.Ql * , 212or set to 213.Ql 0 , 214then the size of 215the log file is not taken into account when determining when to trim the 216log file. 217By default, files smaller than 256 bytes are not rotated unless the 218.Sq B 219(binary) flag is set or the 220.Fl F 221option is specified. 222This prevents 223.Nm 224from rotating files consisting solely of a message indicating 225that the log file has been turned over. 226.It Ar when 227The 228.Ar when 229field can consist of an interval, a specific time, or both. 230If the 231.Ar when 232field consists of an asterisk 233.Pq Ql \&* , 234log rotation will depend only on the contents of the 235.Ar size 236field. 237Otherwise, the 238.Ar when 239field consists of an optional interval in hours, possibly followed 240by an 241.So Li \&@ Sc Ns -sign 242and a time in a restricted 243.St -iso8601 244format or by a 245.So Li \&$ Sc Ns -sign 246and a time specification for logfile rotation at a fixed time once 247per day, per week or per month. 248.Pp 249If a time is specified, the log file will only be trimmed if 250.Nm 251is run within one hour of the specified time. 252If an interval is specified, the log file will be trimmed if that 253many hours have passed since the last rotation. 254When both a time and an interval are specified, both conditions 255must be satisfied for the rotation to take place. 256If the 257.Ar size 258field is set and not 259.Ql * 260or 261.Ql 0 , 262the file will be rotated either if the size is 263exceeded or the specified time or interval is reached. 264.Pp 265There is no provision for the specification of a time zone. 266There is little point in specifying an explicit minutes or seconds 267component in the current implementation, since the only comparison is 268.Sq within the hour . 269.Pp 270.Sy ISO 8601 restricted time format: 271The lead-in character for a restricted 272.St -iso8601 273time is an 274.So Li \&@ Sc Ns -sign . 275The particular format of the time in restricted 276.St -iso8601 277is: 278.Sm off 279.Oo Oo Oo Oo Oo 280.Va \&cc Oc 281.Va \&yy Oc 282.Va \&mm Oc 283.Va \&dd Oc 284.Oo Va \&T 285.Oo Va \&HH 286.Oo Va \&MM 287.Oo Va \&SS 288.Oc Oc Oc Oc Oc . 289.Sm on 290Optional date fields default to the appropriate component of the 291current date; optional time fields default to midnight. 292For example, if today is January 22, 1999, the following date specifications 293are all equivalent: 294.Pp 295.Bl -item -compact -offset indent 296.It 297.Ql 19990122T000000 298.It 299.Ql 990122T000000 300.It 301.Ql 0122T000000 302.It 303.Ql 22T000000 304.It 305.Ql T000000 306.It 307.Ql T0000 308.It 309.Ql T00 310.It 311.Ql 22T 312.It 313.Ql \&T 314.It 315.Ql \& 316.El 317.Pp 318.Sy Day, week and month time format: 319The lead-in character for day, week and month specification is a 320dollar sign 321.Pq $ . 322The particular format of day, week and month specification is: 323.Op Li D Ns Ar HH , 324.Op Li W Ns Ar w Ns Op Li D Ns Ar HH , 325and 326.Op Li M Ns Ar dd Ns Op Li D Ns Ar HH , 327respectively. 328Optional time fields default to midnight. 329The ranges for day and hour specifications are: 330.Pp 331.Bl -tag -width Ds -compact -offset indent 332.It Ar HH 333hours, range 0 ... 23 334.It Ar w 335day of week, range 0 ... 6, 0 = Sunday 336.It Ar dd 337day of month, range 1 ... 31, or the letter 338.Em L 339or 340.Em l 341to specify the last day of the month. 342.El 343.Pp 344.Sy Some examples: 345.Bl -tag -width Ds -compact -offset indent 346.It Li $D0 347rotate every night at midnight 348(same as 349.Li @T00 ) 350.It Li $D23 351rotate every day at 23:00 hr 352(same as 353.Li @T23 ) 354.It Li $W0D23 355rotate every week on Sunday at 23:00 hr 356.It Li $W5D16 357rotate every week on Friday at 16:00 hr 358.It Li $M1D0 359rotate on the first day of every month at midnight 360(i.e., the start of the day; same as 361.Li @01T00 ) 362.It Li $M5D6 363rotate on every 5th day of the month at 6:00 hr 364(same as 365.Li @05T06 ) 366.El 367.It Ar flags 368The optional 369.Ar flags 370field specifies if the archives should have any special processing 371done to the archived log files. 372The 373.Sq Z 374flag will make the archive 375files compressed to save space using 376.Xr gzip 1 377or 378.Xr compress 1 , 379depending on compilation options. 380The 381.Sq B 382flag means that the file is a 383binary file, and so the ASCII message which 384.Nm 385inserts to indicate the fact that the logs have been turned over 386should not be included. 387The 388.Sq M 389flag marks this entry as a monitored 390log file. 391The 392.Sq F 393flag specifies that symbolic links should be followed. 394.It Ar monitor 395Specify the username (or email address) that should receive notification 396messages if this is a monitored log file. 397Notification messages are sent as email; the operator 398deserves what they get if they mark the mail 399log file as monitored. 400This field is only valid when the 401.Sq M 402flag is set. 403.It Ar pid_file 404This optional field specifies a file containing the PID of a process to send a 405signal (usually 406.Dv SIGHUP ) 407to instead of 408.Pa /var/run/syslog.pid . 409.It Ar signal 410This optional field specifies the signal to send to the process instead of 411.Dv SIGHUP . 412Signal names 413must start with 414.Dq SIG 415and be the signal name, not the number, e.g., 416.Dv SIGUSR1 . 417.It Ar command 418This optional field specifies a command to run instead of sending a signal 419to the process. 420The command must be enclosed in double quotes 421.Pq Ql \&" . 422The empty string, 423.Ql \&"\&" , 424can be used to prevent 425.Nm 426from sending a signal or running a command. 427You cannot specify both a command and a PID file. 428.Em NOTE: 429If you specify a command to be run, 430.Nm 431will not send a 432.Dv SIGHUP to 433.Xr syslogd 8 . 434.El 435.Sh FILES 436.Bl -tag -width /etc/newsyslog.conf 437.It Pa /etc/newsyslog.conf 438default configuration file 439.El 440.Sh EXIT STATUS 441.Ex -std 442.Sh SEE ALSO 443.Xr compress 1 , 444.Xr gzip 1 , 445.Xr syslog 3 , 446.Xr syslogd 8 447.Sh AUTHORS 448.An Theodore Ts'o , 449MIT Project Athena 450.br 451Copyright 1987, Massachusetts Institute of Technology 452