1.\" $OpenBSD: newsyslog.8,v 1.53 2015/11/14 01:22:04 jmc 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: November 14 2015 $ 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. 256.Pp 257There is no provision for the specification of a time zone. 258There is little point in specifying an explicit minutes or seconds 259component in the current implementation, since the only comparison is 260.Sq within the hour . 261.Pp 262.Sy ISO 8601 restricted time format: 263The lead-in character for a restricted 264.St -iso8601 265time is an 266.So Li \&@ Sc Ns -sign . 267The particular format of the time in restricted 268.St -iso8601 269is: 270.Sm off 271.Oo Oo Oo Oo Oo 272.Va \&cc Oc 273.Va \&yy Oc 274.Va \&mm Oc 275.Va \&dd Oc 276.Oo Va \&T 277.Oo Va \&HH 278.Oo Va \&MM 279.Oo Va \&SS 280.Oc Oc Oc Oc Oc . 281.Sm on 282Optional date fields default to the appropriate component of the 283current date; optional time fields default to midnight. 284For example, if today is January 22, 1999, the following date specifications 285are all equivalent: 286.Pp 287.Bl -item -compact -offset indent 288.It 289.Ql 19990122T000000 290.It 291.Ql 990122T000000 292.It 293.Ql 0122T000000 294.It 295.Ql 22T000000 296.It 297.Ql T000000 298.It 299.Ql T0000 300.It 301.Ql T00 302.It 303.Ql 22T 304.It 305.Ql \&T 306.It 307.Ql \& 308.El 309.Pp 310.Sy Day, week and month time format: 311The lead-in character for day, week and month specification is a 312dollar sign 313.Pq $ . 314The particular format of day, week and month specification is: 315.Op Li D Ns Ar HH , 316.Op Li W Ns Ar w Ns Op Li D Ns Ar HH , 317and 318.Op Li M Ns Ar dd Ns Op Li D Ns Ar HH , 319respectively. 320Optional time fields default to midnight. 321The ranges for day and hour specifications are: 322.Pp 323.Bl -tag -width Ds -compact -offset indent 324.It Ar HH 325hours, range 0 ... 23 326.It Ar w 327day of week, range 0 ... 6, 0 = Sunday 328.It Ar dd 329day of month, range 1 ... 31, or the letter 330.Em L 331or 332.Em l 333to specify the last day of the month. 334.El 335.Pp 336.Sy Some examples: 337.Bl -tag -width Ds -compact -offset indent 338.It Li $D0 339rotate every night at midnight 340(same as 341.Li @T00 ) 342.It Li $D23 343rotate every day at 23:00 hr 344(same as 345.Li @T23 ) 346.It Li $W0D23 347rotate every week on Sunday at 23:00 hr 348.It Li $W5D16 349rotate every week on Friday at 16:00 hr 350.It Li $M1D0 351rotate on the first day of every month at midnight 352(i.e., the start of the day; same as 353.Li @01T00 ) 354.It Li $M5D6 355rotate on every 5th day of the month at 6:00 hr 356(same as 357.Li @05T06 ) 358.El 359.It Ar flags 360The optional 361.Ar flags 362field specifies if the archives should have any special processing 363done to the archived log files. 364The 365.Sq Z 366flag will make the archive 367files compressed to save space using 368.Xr gzip 1 369or 370.Xr compress 1 , 371depending on compilation options. 372The 373.Sq B 374flag means that the file is a 375binary file, and so the ASCII message which 376.Nm 377inserts to indicate the fact that the logs have been turned over 378should not be included. 379The 380.Sq M 381flag marks this entry as a monitored 382log file. 383The 384.Sq F 385flag specifies that symbolic links should be followed. 386.It Ar monitor 387Specify the username (or email address) that should receive notification 388messages if this is a monitored log file. 389Notification messages are sent as email; the operator 390deserves what they get if they mark the mail 391log file as monitored. 392This field is only valid when the 393.Sq M 394flag is set. 395.It Ar pid_file 396This optional field specifies a file containing the PID of a process to send a 397signal (usually 398.Dv SIGHUP ) 399to instead of 400.Pa /var/run/syslog.pid . 401.It Ar signal 402Specify the signal to send to the process instead of 403.Dv SIGHUP . 404Signal names 405must start with 406.Dq SIG 407and be the signal name, not the number, e.g., 408.Dv SIGUSR1 . 409.It Ar command 410This optional field specifies a command to run instead of sending a signal 411to the process. 412The command must be enclosed in double quotes 413.Pq Ql \&" . 414The empty string, 415.Ql \&"\&" , 416can be used to prevent 417.Nm 418from sending a signal or running a command. 419You cannot specify both a command and a PID file. 420.Em NOTE: 421If you specify a command to be run, 422.Nm 423will not send a 424.Dv SIGHUP to 425.Xr syslogd 8 . 426.El 427.Sh FILES 428.Bl -tag -width /etc/newsyslog.conf 429.It Pa /etc/newsyslog.conf 430default configuration file 431.El 432.Sh SEE ALSO 433.Xr compress 1 , 434.Xr gzip 1 , 435.Xr syslog 3 , 436.Xr syslogd 8 437.Sh AUTHORS 438.An Theodore Ts'o , 439MIT Project Athena 440.br 441Copyright 1987, Massachusetts Institute of Technology 442