1.\" This file contains changes from the Open Software Foundation. 2.\" 3.\" from: @(#)newsyslog.8 4.\" $FreeBSD$ 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 March 10, 2004 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 CFnrsv 29.Op Fl R Ar tagname 30.Op Fl a Ar directory 31.Op Fl f Ar config_file 32.Op Ar 33.Sh DESCRIPTION 34The 35.Nm 36utility should be scheduled to run periodically by 37.Xr cron 8 . 38When it is executed it archives log files if necessary. If a log file 39is determined to require archiving, 40.Nm 41rearranges the files so that 42.Dq Va logfile 43is empty, 44.Dq Va logfile Ns Li \&.0 45has 46the last period's logs in it, 47.Dq Va logfile Ns Li \&.1 48has the next to last 49period's logs in it, and so on, up to a user-specified number of 50archived logs. Optionally the archived logs can be compressed to save 51space. 52.Pp 53A log can be archived for three reasons: 54.Bl -enum -offset indent 55.It 56It is larger than the configured size (in kilobytes). 57.It 58A configured number of hours have elapsed since the log was last 59archived. 60.It 61This is the specific configured hour for rotation of the log. 62.El 63.Pp 64The granularity of 65.Nm 66is dependent on how often it is scheduled to run by 67.Xr cron 8 . 68Since the program is quite fast, it may be scheduled to run every hour 69without any ill effects, 70and mode three (above) assumes that this is so. 71.Sh OPTIONS 72The following options can be used with 73.Nm : 74.Bl -tag -width indent 75.It Fl f Ar config_file 76Instruct 77.Nm 78to use 79.Ar config_file 80instead of 81.Pa /etc/newsyslog.conf 82for its configuration file. 83.It Fl a Ar directory 84Specify a 85.Ar directory 86into which archived log files will be written. 87If a relative path is given, 88it is appended to the path of each log file 89and the resulting path is used as the directory 90into which the archived log for that log file will be written. 91If an absolute path is given, 92all archived logs are written into the given 93.Ar directory . 94If any component of the path 95.Ar directory 96does not exist, 97it will be created when 98.Nm 99is run. 100.It Fl v 101Place 102.Nm 103in verbose mode. In this mode it will print out each log and its 104reasons for either trimming that log or skipping it. 105.It Fl n 106Cause 107.Nm 108not to trim the logs, but to print out what it would do if this option 109were not specified. 110.It Fl r 111Remove the restriction that 112.Nm 113must be running as root. Of course, 114.Nm 115will not be able to send a HUP signal to 116.Xr syslogd 8 117so this option should only be used in debugging. 118.It Fl s 119Specify that 120.Nm 121should not send any signals to any daemon processes that it would 122normally signal when rotating a log file. 123For any log file which is rotated, this option will usually also 124mean the rotated log file will not be compressed if there is a 125daemon which would have been signalled without this option. 126However, this option is most likely to be useful when specified 127with the 128.Fl R 129option, and in that case the compression will be done. 130.It Fl C 131If specified once, then 132.Nm 133will create any log files which do not exist, and which have the 134.Sy C 135flag specified in their config file entry. 136If specified multiple times, then 137.Nm 138will create all log files which do not already exist. 139If log files are given on the command-line, then the 140.Fl C 141or 142.Fl CC 143will only apply to those specific log files. 144.It Fl F 145Force 146.Nm 147to trim the logs, even if the trim conditions have not been met. This 148option is useful for diagnosing system problems by providing you with 149fresh logs that contain only the problems. 150.It Fl R Ar tagname 151Specify that 152.Nm 153should rotate a given list of files, even if trim conditions are not 154met for those files. 155The 156.Ar tagname 157is only used in the messages written to the log files which are 158rotated. 159This differs from the 160.Fl F 161option in that one or more log files must also be specified, so that 162.Nm 163will only operate on those specific files. 164This option is mainly intended for the daemons or programs which write 165some log files, and want to trigger a rotate based on their own criteria. 166With this option they can execute 167.Nm 168to trigger the rotate when they want it to happen, and still give the 169system administrator a way to specify the rules of rotation (such as how 170many backup copies are kept, and what kind of compression is done). 171When a daemon does execute 172.Nm 173with the 174.Fl R 175option, it should make sure all of the log files are closed before 176calling 177.Nm , 178and then it should re-open the files after 179.Nm 180returns. 181Usually the calling process will also want to specify the 182.Fl s 183option, so 184.Nm 185will not send a signal to the very process which called it to force 186the rotate. 187Skipping the signal step will also mean that 188.Nm 189will return faster, since 190.Nm 191normally waits a few seconds after any signal that is sent. 192.El 193.Pp 194If additional command line arguments are given, 195.Nm 196will only examine log files that match those arguments; otherwise, it 197will examine all files listed in the configuration file. 198.Sh FILES 199.Bl -tag -width /etc/newsyslog.confxxxx -compact 200.It Pa /etc/newsyslog.conf 201.Nm 202configuration file 203.El 204.Sh BUGS 205Doesn't yet automatically read the logs to find security breaches. 206.Sh AUTHORS 207.An Theodore Ts'o , 208MIT Project Athena 209.Pp 210Copyright 1987, Massachusetts Institute of Technology 211.Sh COMPATIBILITY 212Previous versions of the 213.Nm 214utility used the dot (``.'') character to 215distinguish the group name. 216Beginning with 217.Fx 3.3 , 218this has been changed to a colon (``:'') character so that user and group 219names may contain the dot character. The dot (``.'') character is still 220accepted for backwards compatibility. 221.Sh "SEE ALSO" 222.Xr bzip 1 , 223.Xr gzip 1 , 224.Xr syslog 3 , 225.Xr newsyslog.conf 5 , 226.Xr chown 8 , 227.Xr syslogd 8 228