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