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