1.\" This file contains changes from the Open Software Foundation. 2.\" 3.\" from: @(#)newsyslog.8 4.\" 5.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 6.\" 7.\" Permission to use, copy, modify, and distribute this software 8.\" and its documentation for any purpose and without fee is 9.\" hereby granted, provided that the above copyright notice 10.\" appear in all copies and that both that copyright notice and 11.\" this permission notice appear in supporting documentation, 12.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 13.\" used in advertising or publicity pertaining to distribution 14.\" of the software without specific, written prior permission. 15.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 16.\" the suitability of this software for any purpose. It is 17.\" provided "as is" without express or implied warranty. 18.\" 19.Dd November 10, 2018 20.Dt NEWSYSLOG 8 21.Os 22.Sh NAME 23.Nm newsyslog 24.Nd maintain system log files to manageable sizes 25.Sh SYNOPSIS 26.Nm 27.Op Fl CFNPnrsv 28.Op Fl a Ar directory 29.Op Fl d Ar directory 30.Op Fl f Ar config_file 31.Op Fl S Ar pidfile 32.Op Fl t Ar timefmt 33.Op Oo Fl R Ar tagname Oc 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. 53It is also possible to let archived log filenames be created using the 54time the log file was archived instead of the sequential number using 55the 56.Fl t 57option. 58Optionally the archived logs can be compressed to save 59space. 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. 128This option implies the 129.Fl r 130option. 131.It Fl r 132Remove the restriction that 133.Nm 134must be running as root. 135Of course, 136.Nm 137will not be able to send a HUP signal to 138.Xr syslogd 8 139so this option should only be used in debugging. 140.It Fl s 141Specify that 142.Nm 143should not send any signals to any daemon processes that it would 144normally signal when rotating a log file. 145For any log file which is rotated, this option will usually also 146mean the rotated log file will not be compressed if there is a 147daemon which would have been signalled without this option. 148However, this option is most likely to be useful when specified 149with the 150.Fl R 151option, and in that case the compression will be done. 152.It Fl t Ar timefmt 153If specified 154.Nm 155will create the 156.Dq rotated 157logfiles using the specified time format instead of the default 158sequential filenames. 159The filename used will be kept until it is deleted. 160The time format is described in the 161.Xr strftime 3 162manual page. 163If the 164.Ar timefmt 165argument is set to an empty string or the string 166.Dq DEFAULT , 167the default built in time format 168is used. 169If the 170.Ar timefmt 171string is changed the old files created using the previous time format 172will not be automatically removed (unless the new format is very 173similar to the old format). 174This is also the case when changing from sequential filenames to time 175based file names, and the other way around. 176The time format should contain at least year, month, day, and hour to 177make sure rotating of old logfiles can select the correct logfiles. 178.It Fl C 179If specified once, then 180.Nm 181will create any log files which do not exist, and which have the 182.Sy C 183flag specified in their config file entry. 184If specified multiple times, then 185.Nm 186will create all log files which do not already exist. 187If log files are given on the command-line, then the 188.Fl C 189or 190.Fl CC 191will only apply to those specific log files. 192.It Fl F 193Force 194.Nm 195to trim the logs, even if the trim conditions have not been met. 196This 197option is useful for diagnosing system problems by providing you with 198fresh logs that contain only the problems. 199.It Fl N 200Do not perform any rotations. 201This option is intended to be used with the 202.Fl C 203or 204.Fl CC 205options when creating log files is the only objective. 206.It Fl P 207Prevent further action if we should send signal but the 208.Dq pidfile 209is empty or does not exist. 210.It Fl R Ar tagname 211Specify that 212.Nm 213should rotate a given list of files, even if trim conditions are not 214met for those files. 215The 216.Ar tagname 217is only used in the messages written to the log files which are 218rotated. 219This differs from the 220.Fl F 221option in that one or more log files must also be specified, so that 222.Nm 223will only operate on those specific files. 224This option is mainly intended for the daemons or programs which write 225some log files, and want to trigger a rotate based on their own criteria. 226With this option they can execute 227.Nm 228to trigger the rotate when they want it to happen, and still give the 229system administrator a way to specify the rules of rotation (such as how 230many backup copies are kept, and what kind of compression is done). 231When a daemon does execute 232.Nm 233with the 234.Fl R 235option, it should make sure all of the log files are closed before 236calling 237.Nm , 238and then it should re-open the files after 239.Nm 240returns. 241Usually the calling process will also want to specify the 242.Fl s 243option, so 244.Nm 245will not send a signal to the very process which called it to force 246the rotate. 247Skipping the signal step will also mean that 248.Nm 249will return faster, since 250.Nm 251normally waits a few seconds after any signal that is sent. 252.It Fl S Ar pidfile 253Use 254.Ar pidfile 255as 256.Xr syslogd 8 Ns 's 257pidfile. 258.El 259.Pp 260If additional command line arguments are given, 261.Nm 262will only examine log files that match those arguments; otherwise, it 263will examine all files listed in the configuration file. 264.Sh FILES 265.Bl -tag -width /usr/local/etc/newsyslog.conf.d -compact 266.It Pa /etc/newsyslog.conf 267.Nm 268configuration file 269.It Pa /etc/newsyslog.conf.d 270By default each file in this directory ending in '.conf' and not beginning with 271a '.' will be included by the default 272.Pa newsyslog.conf . 273.It Pa /usr/local/etc/newsyslog.conf.d 274By default each file in this directory ending in '.conf' and not beginning with 275a '.' will be included by the default 276.Pa newsyslog.conf . 277.El 278.Sh COMPATIBILITY 279Previous versions of the 280.Nm 281utility used the dot (``.'') character to 282distinguish the group name. 283Beginning with 284.Fx 3.3 , 285this has been changed to a colon (``:'') character so that user and group 286names may contain the dot character. 287The dot (``.'') character is still 288accepted for backwards compatibility. 289.Sh SEE ALSO 290.Xr bzip2 1 , 291.Xr gzip 1 , 292.Xr xz 1 , 293.Xr zstd 1 , 294.Xr syslog 3 , 295.Xr newsyslog.conf 5 , 296.Xr chown 8 , 297.Xr syslogd 8 298.Sh HISTORY 299The 300.Nm 301utility originated from 302.Nx 303and first appeared in 304.Fx 2.2 . 305.Sh AUTHORS 306.An Theodore Ts'o , 307MIT Project Athena 308.Pp 309Copyright 1987, Massachusetts Institute of Technology 310