1.\" $OpenBSD: newsyslog.8,v 1.49 2011/09/26 19:41:56 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: September 26 2011 $ 45.Dt NEWSYSLOG 8 46.Os 47.Sh NAME 48.Nm newsyslog 49.Nd rotate log files 50.Sh SYNOPSIS 51.Nm newsyslog 52.Op Fl Fmnrv 53.Op Fl a Ar directory 54.Op Fl f Ar config_file 55.Op Ar log ... 56.Sh DESCRIPTION 57The 58.Nm 59utility rotates log files when they exceed a configurable size or age. 60The 61.Ar log 62file is renamed to 63.Pa log.0 64and an empty file is created in its place. 65An archive of older logs may be kept: 66in order of increasing age, these files are named 67.Pa log.1 , 68.Pa log.2 , 69and so on. 70When their number exceeds a given limit, the oldest is removed. 71The archived logs may also be compressed. 72.Pp 73The options are as follows: 74.Bl -tag -width Ds 75.It Fl a Ar directory 76Specify a 77.Ar directory 78into which archived log files will be written. 79If 80.Ar directory 81is a relative path, it is appended to the parent directory 82of each log and the archived log is stored in the result. 83If an absolute path is given, all archived logs are stored in the given 84.Ar directory . 85If 86.Ar directory 87does not exist for a specified log, it is ignored for that entry and 88the log is rotated as if the 89.Fl a 90option was not specified. 91.It Fl F 92Force 93.Nm 94to trim logs regardless of the size and/or age requirements specified in 95.Pa /etc/newsyslog.conf . 96This option may be combined with the 97.Fl n 98or 99.Fl v 100flags to aid in debugging problems with 101.Pa /etc/newsyslog.conf . 102.It Fl f Ar config_file 103Use 104.Ar config_file 105instead of 106.Pa /etc/newsyslog.conf 107for the configuration file. 108.It Fl m 109Monitoring mode; only entries marked with an 110.Sq M 111in flags are processed. 112For each log file being monitored, any log output since the last time 113.Nm 114was run with the 115.Fl m 116flag is mailed to the user listed in the monitor notification section. 117.It Fl n 118Do not trim the logs, but instead print out what would be done if this option 119were not specified. 120.It Fl r 121Removes the restriction that 122.Nm 123must be running as root. 124Note that in this mode 125.Nm 126will not be able to send a 127.Dv SIGHUP 128signal to 129.Xr syslogd 8 . 130.It Fl v 131Place 132.Nm newsyslog 133in verbose mode. 134In this mode it will print out each log and its 135reasons for either trimming that log or skipping it. 136.El 137.Pp 138In the default system configuration, 139.Nm 140is run by 141.Xr cron 8 , 142but it may also be run manually. 143If one or more 144.Ar log 145files are specified on the command line, only the specified files are 146rotated. 147Note that each 148.Ar log 149specified must have an entry in 150.Pa /etc/newsyslog.conf . 151.Pp 152A log can be archived because of two reasons: 153The log file can have 154grown bigger than a preset size in kilobytes, or a preset number of 155hours may have elapsed since the last log archive. 156The granularity of 157.Nm 158is dependent on how often it is scheduled to run in 159.Xr cron 8 . 160Since the program is quite fast, it may be scheduled to run every hour 161without any ill effects. 162.Pp 163When starting up, 164.Nm 165reads in a configuration file to determine which logs should be looked 166at. 167By default, this configuration file is 168.Pa /etc/newsyslog.conf . 169Each line of the file contains information about a particular log file 170that should be handled by 171.Nm newsyslog . 172Each line has five mandatory fields and up to three optional fields, with 173whitespace separating each field. 174Blank lines or lines beginning with a hash mark 175.Pq Ql # 176are ignored. 177The fields of the configuration file are as 178follows: 179.Bl -tag -width XXXXXXXXXXXXXXXX 180.It Ar logfile_name 181The full pathname of the system log file to be archived. 182.It Ar owner:group 183This optional field specifies the owner and group for the archive file. 184The 185.Ql \&: 186is essential, even if the 187.Ar owner 188or 189.Ar group 190field is left blank. 191The fields may be numeric, or a name which is looked up 192in the system password and group databases. 193For backwards compatibility, a 194.Ql \&. 195may be used instead of a 196.Ql \&: . 197If either 198.Ar owner 199or 200.Ar group 201is not specified, the owner and/or group of the existing log file is used. 202.It Ar mode 203File mode (in octal) to use for created log files and archives. 204.It Ar count 205The number of archives to be kept besides the log file itself. 206.It Ar size 207When the size of the log file (in kilobytes) reaches this point, the log 208file is trimmed as described above. 209If this field is replaced by an 210.Ql * , 211or set to 212.Ql 0 , 213then the size of 214the log file is not taken into account when determining when to trim the 215log file. 216By default, files smaller than 256 bytes are not rotated unless the 217.Sq B 218(binary) flag is set or the 219.Fl F 220option is specified. 221This prevents 222.Nm 223from rotating files consisting solely of a message indicating 224that the log file has been turned over. 225.It Ar when 226The 227.Ar when 228field can consist of an interval, a specific time, or both. 229If the 230.Ar when 231field consists of an asterisk 232.Pq Ql \&* , 233log rotation will depend only on the contents of the 234.Ar size 235field. 236Otherwise, the 237.Ar when 238field consists of an optional interval in hours, possibly followed 239by an 240.So Li \&@ Sc Ns -sign 241and a time in a restricted 242.St -iso8601 243format or by a 244.So Li \&$ Sc Ns -sign 245and a time specification for logfile rotation at a fixed time once 246per day, per week or per month. 247.Pp 248If a time is specified, the log file will only be trimmed if 249.Nm 250is run within one hour of the specified time. 251If an interval is specified, the log file will be trimmed if that 252many hours have passed since the last rotation. 253When both a time and an interval are specified, both conditions 254must be satisfied for the rotation to take place. 255.Pp 256There is no provision for the specification of a time zone. 257There is little point in specifying an explicit minutes or seconds 258component in the current implementation, since the only comparison is 259.Sq within the hour . 260.Pp 261.Sy ISO 8601 restricted time format: 262The lead-in character for a restricted 263.St -iso8601 264time is an 265.So Li \&@ Sc Ns -sign . 266The particular format of the time in restricted 267.St -iso8601 268is: 269.Sm off 270.Oo Oo Oo Oo Oo 271.Va \&cc Oc 272.Va \&yy Oc 273.Va \&mm Oc 274.Va \&dd Oc 275.Oo Va \&T 276.Oo Va \&HH 277.Oo Va \&MM 278.Oo Va \&SS 279.Oc Oc Oc Oc Oc . 280.Sm on 281Optional date fields default to the appropriate component of the 282current date; optional time fields default to midnight. 283For example, if today is January 22, 1999, the following date specifications 284are all equivalent: 285.Pp 286.Bl -item -compact -offset indent 287.It 288.Ql 19990122T000000 289.It 290.Ql 990122T000000 291.It 292.Ql 0122T000000 293.It 294.Ql 22T000000 295.It 296.Ql T000000 297.It 298.Ql T0000 299.It 300.Ql T00 301.It 302.Ql 22T 303.It 304.Ql \&T 305.It 306.Ql \& 307.El 308.Pp 309.Sy Day, week and month time format: 310The lead-in character for day, week and month specification is a 311dollar sign 312.Pq $ . 313The particular format of day, week and month specification is: 314.Op Li D Ns Ar HH , 315.Op Li W Ns Ar w Ns Op Li D Ns Ar HH , 316and 317.Op Li M Ns Ar dd Ns Op Li D Ns Ar HH , 318respectively. 319Optional time fields default to midnight. 320The ranges for day and hour specifications are: 321.Pp 322.Bl -tag -width Ds -compact -offset indent 323.It Ar HH 324hours, range 0 ... 23 325.It Ar w 326day of week, range 0 ... 6, 0 = Sunday 327.It Ar dd 328day of month, range 1 ... 31, or the letter 329.Em L 330or 331.Em l 332to specify the last day of the month. 333.El 334.Pp 335.Sy Some examples: 336.Bl -tag -width Ds -compact -offset indent 337.It Li $D0 338rotate every night at midnight 339(same as 340.Li @T00 ) 341.It Li $D23 342rotate every day at 23:00 hr 343(same as 344.Li @T23 ) 345.It Li $W0D23 346rotate every week on Sunday at 23:00 hr 347.It Li $W5D16 348rotate every week on Friday at 16:00 hr 349.It Li $M1D0 350rotate on the first day of every month at midnight 351(i.e., the start of the day; same as 352.Li @01T00 ) 353.It Li $M5D6 354rotate on every 5th day of the month at 6:00 hr 355(same as 356.Li @05T06 ) 357.El 358.Pp 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 391.Xr sendmail 8 392log file as monitored. 393This field is only valid when the 394.Sq M 395flag is set. 396.It Ar pid_file 397This optional field specifies a file containing the PID of a process to send a 398signal (usually 399.Dv SIGHUP ) 400to instead of 401.Pa /var/run/syslog.pid . 402.It Ar signal 403Specify the signal to send to the process instead of 404.Dv SIGHUP . 405Signal names 406must start with 407.Dq SIG 408and be the signal name, not the number, e.g., 409.Dv SIGUSR1 . 410.It Ar command 411This optional field specifies a command to run instead of sending a signal 412to the process. 413The command must be enclosed in double quotes 414.Pq Ql \&" . 415The empty string, 416.Ql \&"\&" , 417can be used to prevent 418.Nm 419from sending a signal or running a command. 420You cannot specify both a command and a PID file. 421.Em NOTE: 422If you specify a command to be run, 423.Nm 424will not send a 425.Dv SIGHUP to 426.Xr syslogd 8 . 427.El 428.Sh FILES 429.Bl -tag -width /etc/newsyslog.conf 430.It Pa /etc/newsyslog.conf 431default configuration file 432.El 433.Sh SEE ALSO 434.Xr compress 1 , 435.Xr gzip 1 , 436.Xr syslog 3 , 437.Xr syslogd 8 438.Sh AUTHORS 439.Bd -unfilled 440Theodore Ts'o, MIT Project Athena 441Copyright 1987, Massachusetts Institute of Technology 442.Ed 443