1.\" This file contains changes from the Open Software Foundation. 2.\" 3.\" from: @(#)newsyslog.8 4.\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.8,v 1.57 2011/01/31 11:30:26 mm Exp $ 5.\" 6.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 7.\" 8.\" Permission to use, copy, modify, and distribute this software 9.\" and its documentation for any purpose and without fee is 10.\" hereby granted, provided that the above copyright notice 11.\" appear in all copies and that both that copyright notice and 12.\" this permission notice appear in supporting documentation, 13.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 14.\" used in advertising or publicity pertaining to distribution 15.\" of the software without specific, written prior permission. 16.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 17.\" the suitability of this software for any purpose. It is 18.\" provided "as is" without express or implied warranty. 19.\" 20.Dd January 31, 2011 21.Dt NEWSYSLOG 8 22.Os 23.Sh NAME 24.Nm newsyslog 25.Nd maintain system log files to manageable sizes 26.Sh SYNOPSIS 27.Nm 28.Op Fl CFNPnrsv 29.Op Fl R Ar tagname 30.Op Fl S Ar pidfile 31.Op Fl a Ar directory 32.Op Fl d Ar directory 33.Op Fl f Ar config_file 34.Op Fl t Ar timefmt 35.Op Ar 36.Sh DESCRIPTION 37The 38.Nm 39utility should be scheduled to run periodically by 40.Xr cron 8 . 41When it is executed it archives log files if necessary. 42If a log file is determined to require archiving, 43.Nm 44rearranges the files so that 45.Dq Va logfile 46is empty, 47.Dq Va logfile Ns Li \&.0 48has 49the last period's logs in it, 50.Dq Va logfile Ns Li \&.1 51has the next to last 52period's logs in it, and so on, up to a user-specified number of 53archived logs. 54It is also possible to let archived log filenames be created using the 55time the log file was archived instead of the sequential number using 56the 57.Fl t 58option. 59Optionally the archived logs can be compressed to save space. 60.Pp 61A log can be archived for three reasons: 62.Bl -enum -offset indent 63.It 64It is larger than the configured size (in kilobytes). 65.It 66A configured number of hours have elapsed since the log was last 67archived. 68.It 69This is the specific configured hour for rotation of the log. 70.El 71.Pp 72The granularity of 73.Nm 74is dependent on how often it is scheduled to run by 75.Xr cron 8 . 76Since the program is quite fast, it may be scheduled to run every hour 77without any ill effects, 78and mode three (above) assumes that this is so. 79.Sh OPTIONS 80The following options can be used with 81.Nm : 82.Bl -tag -width indent 83.It Fl f Ar config_file 84Instruct 85.Nm 86to use 87.Ar config_file 88instead of 89.Pa /etc/newsyslog.conf 90for its configuration file. 91.It Fl a Ar directory 92Specify a 93.Ar directory 94into which archived log files will be written. 95If a relative path is given, 96it is appended to the path of each log file 97and the resulting path is used as the directory 98into which the archived log for that log file will be written. 99If an absolute path is given, 100all archived logs are written into the given 101.Ar directory . 102If any component of the path 103.Ar directory 104does not exist, 105it will be created when 106.Nm 107is run. 108.It Fl d Ar directory 109Specify a 110.Ar directory 111which all log files will be relative to. 112To allow archiving of logs outside the root, the 113.Ar directory 114passed to the 115.Fl a 116option is unaffected. 117.It Fl v 118Place 119.Nm 120in verbose mode. 121In this mode it will print out each log and its 122reasons for either trimming that log or skipping it. 123.It Fl n 124Cause 125.Nm 126not to trim the logs, but to print out what it would do if this option 127were not specified. 128.It Fl r 129Remove the restriction that 130.Nm 131must be running as root. 132Of course, 133.Nm 134will not be able to send a HUP signal to 135.Xr syslogd 8 136so this option should only be used in debugging. 137.It Fl s 138Specify that 139.Nm 140should not send any signals to any daemon processes that it would 141normally signal when rotating a log file. 142For any log file which is rotated, this option will usually also 143mean the rotated log file will not be compressed if there is a 144daemon which would have been signalled without this option. 145However, this option is most likely to be useful when specified 146with the 147.Fl R 148option, and in that case the compression will be done. 149.It Fl t Ar timefmt 150If specified 151.Nm 152will create the 153.Dq rotated 154logfiles using the specified time format instead of the default 155sequential filenames. 156The time format is described in the 157.Xr strftime 3 158manual page. 159If the 160.Ar timefmt 161argument is set to an empty string or the string 162.Dq DEFAULT , 163the default built in time format 164is used. 165If the 166.Ar timefmt 167string is changed the old files created using the previous time format 168will not be automatically removed (unless the new format is very 169similar to the old format). 170This is also the case when changing from sequential filenames to time 171based file names, and the other way around. 172The time format should contain at least year, month, day, and hour to 173make sure rotating of old logfiles can select the correct logfiles. 174.It Fl C 175If specified once, then 176.Nm 177will create any log files which do not exist, and which have the 178.Sy C 179flag specified in their config file entry. 180If specified multiple times, then 181.Nm 182will create all log files which do not already exist. 183If log files are given on the command-line, then the 184.Fl C 185or 186.Fl CC 187will only apply to those specific log files. 188.It Fl F 189Force 190.Nm 191to trim the logs, even if the trim conditions have not been met. 192This option is useful for diagnosing system problems by providing you with 193fresh logs that contain only the problems. 194.It Fl N 195Do not perform any rotations. 196This option is intended to be used with the 197.Fl C 198or 199.Fl CC 200options when creating log files is the only objective. 201.It Fl P 202Prevent further action if we should send signal but the 203.Dq pidfile 204is empty or does not exist. 205.It Fl R Ar tagname 206Specify that 207.Nm 208should rotate a given list of files, even if trim conditions are not 209met for those files. 210The 211.Ar tagname 212is only used in the messages written to the log files which are 213rotated. 214This differs from the 215.Fl F 216option in that one or more log files must also be specified, so that 217.Nm 218will only operate on those specific files. 219This option is mainly intended for the daemons or programs which write 220some log files, and want to trigger a rotate based on their own criteria. 221With this option they can execute 222.Nm 223to trigger the rotate when they want it to happen, and still give the 224system administrator a way to specify the rules of rotation (such as how 225many backup copies are kept, and what kind of compression is done). 226When a daemon does execute 227.Nm 228with the 229.Fl R 230option, it should make sure all of the log files are closed before 231calling 232.Nm , 233and then it should re-open the files after 234.Nm 235returns. 236Usually the calling process will also want to specify the 237.Fl s 238option, so 239.Nm 240will not send a signal to the very process which called it to force 241the rotate. 242Skipping the signal step will also mean that 243.Nm 244will return faster, since 245.Nm 246normally waits a few seconds after any signal that is sent. 247.It Fl S Ar pidfile 248Use 249.Ar pidfile 250as 251.Xr syslogd 8 Ns 's 252pidfile. 253.El 254.Pp 255If additional command line arguments are given, 256.Nm 257will only examine log files that match those arguments; otherwise, it 258will examine all files listed in the configuration file. 259.Sh FILES 260.Bl -tag -width /etc/newsyslog.confxxxx -compact 261.It Pa /etc/newsyslog.conf 262.Nm 263configuration file 264.El 265.Sh COMPATIBILITY 266Previous versions of the 267.Nm 268utility used the dot (``.'') character to 269distinguish the group name. 270Beginning with 271.Fx 3.3 , 272this has been changed to a colon (``:'') character so that user and group 273names may contain the dot character. 274The dot (``.'') character is still accepted for backwards compatibility. 275.Sh SEE ALSO 276.Xr bzip2 1 , 277.Xr gzip 1 , 278.Xr xz 1 , 279.Xr syslog 3 , 280.Xr newsyslog.conf 5 , 281.Xr chown 8 , 282.Xr syslogd 8 283.Sh HISTORY 284The 285.Nm 286utility originated from 287.Nx 288and first appeared in 289.Fx 2.2 . 290.Sh AUTHORS 291.An Theodore Ts'o , 292MIT Project Athena 293.Pp 294Copyright 1987, Massachusetts Institute of Technology 295.Sh BUGS 296Does not yet automatically read the logs to find security breaches. 297