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.51 2005/06/14 12:26:35 ru Exp $ 5.\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.8,v 1.4 2007/05/12 08:52:00 swildner Exp $ 6.\" 7.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 8.\" 9.\" Permission to use, copy, modify, and distribute this software 10.\" and its documentation for any purpose and without fee is 11.\" hereby granted, provided that the above copyright notice 12.\" appear in all copies and that both that copyright notice and 13.\" this permission notice appear in supporting documentation, 14.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 15.\" used in advertising or publicity pertaining to distribution 16.\" of the software without specific, written prior permission. 17.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 18.\" the suitability of this software for any purpose. It is 19.\" provided "as is" without express or implied warranty. 20.\" 21.Dd May 2, 2007 22.Dt NEWSYSLOG 8 23.Os 24.Sh NAME 25.Nm newsyslog 26.Nd maintain system log files to manageable sizes 27.Sh SYNOPSIS 28.Nm 29.Op Fl CFNnrsv 30.Op Fl R Ar tagname 31.Op Fl a Ar directory 32.Op Fl d Ar directory 33.Op Fl f Ar config_file 34.Op Ar 35.Sh DESCRIPTION 36The 37.Nm 38utility should be scheduled to run periodically by 39.Xr cron 8 . 40When it is executed it archives log files if necessary. 41If a log file is determined to require archiving, 42.Nm 43rearranges the files so that 44.Dq Va logfile 45is empty, 46.Dq Va logfile Ns Li \&.0 47has 48the last period's logs in it, 49.Dq Va logfile Ns Li \&.1 50has the next to last 51period's logs in it, and so on, up to a user-specified number of 52archived logs. 53Optionally the archived logs can be compressed to save space. 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 d Ar directory 103Specify a 104.Ar directory 105which all log files will be relative to. 106To allow archiving of logs outside the root, the 107.Ar directory 108passed to the 109.Fl a 110option is unaffected. 111.It Fl v 112Place 113.Nm 114in verbose mode. 115In this mode it will print out each log and its 116reasons for either trimming that log or skipping it. 117.It Fl n 118Cause 119.Nm 120not to trim the logs, but to print out what it would do if this option 121were not specified. 122.It Fl r 123Remove the restriction that 124.Nm 125must be running as root. 126Of course, 127.Nm 128will not be able to send a HUP signal to 129.Xr syslogd 8 130so this option should only be used in debugging. 131.It Fl s 132Specify that 133.Nm 134should not send any signals to any daemon processes that it would 135normally signal when rotating a log file. 136For any log file which is rotated, this option will usually also 137mean the rotated log file will not be compressed if there is a 138daemon which would have been signalled without this option. 139However, this option is most likely to be useful when specified 140with the 141.Fl R 142option, and in that case the compression will be done. 143.It Fl C 144If specified once, then 145.Nm 146will create any log files which do not exist, and which have the 147.Sy C 148flag specified in their config file entry. 149If specified multiple times, then 150.Nm 151will create all log files which do not already exist. 152If log files are given on the command-line, then the 153.Fl C 154or 155.Fl CC 156will only apply to those specific log files. 157.It Fl F 158Force 159.Nm 160to trim the logs, even if the trim conditions have not been met. 161This option is useful for diagnosing system problems by providing you with 162fresh logs that contain only the problems. 163.It Fl N 164Do not perform any rotations. 165This option is intended to be used with the 166.Fl C 167or 168.Fl CC 169options when creating log files is the only objective. 170.It Fl R Ar tagname 171Specify that 172.Nm 173should rotate a given list of files, even if trim conditions are not 174met for those files. 175The 176.Ar tagname 177is only used in the messages written to the log files which are 178rotated. 179This differs from the 180.Fl F 181option in that one or more log files must also be specified, so that 182.Nm 183will only operate on those specific files. 184This option is mainly intended for the daemons or programs which write 185some log files, and want to trigger a rotate based on their own criteria. 186With this option they can execute 187.Nm 188to trigger the rotate when they want it to happen, and still give the 189system administrator a way to specify the rules of rotation (such as how 190many backup copies are kept, and what kind of compression is done). 191When a daemon does execute 192.Nm 193with the 194.Fl R 195option, it should make sure all of the log files are closed before 196calling 197.Nm , 198and then it should re-open the files after 199.Nm 200returns. 201Usually the calling process will also want to specify the 202.Fl s 203option, so 204.Nm 205will not send a signal to the very process which called it to force 206the rotate. 207Skipping the signal step will also mean that 208.Nm 209will return faster, since 210.Nm 211normally waits a few seconds after any signal that is sent. 212.El 213.Pp 214If additional command line arguments are given, 215.Nm 216will only examine log files that match those arguments; otherwise, it 217will examine all files listed in the configuration file. 218.Sh FILES 219.Bl -tag -width /etc/newsyslog.confxxxx -compact 220.It Pa /etc/newsyslog.conf 221.Nm 222configuration file 223.El 224.Sh COMPATIBILITY 225Previous versions of the 226.Nm 227utility used the dot (``.'') character to 228distinguish the group name. 229Beginning with 230.Fx 3.3 , 231this has been changed to a colon (``:'') character so that user and group 232names may contain the dot character. 233The dot (``.'') character is still accepted for backwards compatibility. 234.Sh "SEE ALSO" 235.Xr bzip2 1 , 236.Xr gzip 1 , 237.Xr syslog 3 , 238.Xr newsyslog.conf 5 , 239.Xr chown 8 , 240.Xr syslogd 8 241.Sh HISTORY 242The 243.Nm 244utility originated from 245.Nx 246and first appeared in 247.Fx 2.2 . 248.Sh AUTHORS 249.An Theodore Ts'o , 250MIT Project Athena 251.Pp 252Copyright 1987, Massachusetts Institute of Technology 253.Sh BUGS 254Does not yet automatically read the logs to find security breaches. 255