1.\" This file contains changes from the Open Software Foundation. 2.\" 3.\" Copyright 1988, 1989 by the Massachusetts Institute of Technology 4.\" 5.\" Permission to use, copy, modify, and distribute this software 6.\" and its documentation for any purpose and without fee is 7.\" hereby granted, provided that the above copyright notice 8.\" appear in all copies and that both that copyright notice and 9.\" this permission notice appear in supporting documentation, 10.\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be 11.\" used in advertising or publicity pertaining to distribution 12.\" of the software without specific, written prior permission. 13.\" M.I.T. and the M.I.T. S.I.P.B. make no representations about 14.\" the suitability of this software for any purpose. It is 15.\" provided "as is" without express or implied warranty. 16.\" 17.Dd December 22, 2023 18.Dt NEWSYSLOG 8 19.Os 20.Sh NAME 21.Nm newsyslog 22.Nd maintain system log files to manageable sizes 23.Sh SYNOPSIS 24.Nm 25.Op Fl CFNPnrsv 26.Op Fl a Ar directory 27.Op Fl c Ar none Ns | Ns Ar legacy Ns | Ns Ar bzip2 Ns | Ns Ar gzip Ns | Ns Ar xz Ns | Ns Ar zstd 28.Op Fl d Ar directory 29.Op Fl f Ar config_file 30.Op Fl S Ar pidfile 31.Op Fl t Ar timefmt 32.Op Oo Fl R Ar tagname Oc 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. 52It is also possible to let archived log filenames be created using the 53time the log file was archived instead of the sequential number using 54the 55.Fl t 56option. 57Optionally the archived logs can be compressed to save 58space. 59.Pp 60A log can be archived for three reasons: 61.Bl -enum -offset indent 62.It 63It is larger than the configured size (in kilobytes). 64.It 65A configured number of hours have elapsed since the log was last 66archived. 67.It 68This is the specific configured hour for rotation of the log. 69.El 70.Pp 71The granularity of 72.Nm 73is dependent on how often it is scheduled to run by 74.Xr cron 8 . 75Since the program is quite fast, it may be scheduled to run every hour 76without any ill effects, 77and mode three (above) assumes that this is so. 78.Sh OPTIONS 79The following options can be used with 80.Nm : 81.Bl -tag -width indent 82.It Fl c Ar none Ns | Ns Ar legacy Ns | Ns Ar bzip2 Ns | Ns Ar gzip Ns | Ns Ar xz Ns | Ns Ar zstd 83Instructs 84.Nm 85to use the specified compression method when a file is flagged for compression. 86The default method is 87.Dq legacy , 88which interprets the 89.Sy J, X, Y, Z 90flags in the configuration file according to their historical meanings. 91This default setting can be overridden by specifying 92.Fl c Ar none , 93which causes 94.Nm 95to ignore all compression flags. 96Alternatively, specifying one of the compression methods: 97.Sy bzip2 , gzip , xz , 98or 99.Sy zstd , 100will apply the chosen method to all files flagged for compression. 101.It Fl f Ar config_file 102Instruct 103.Nm 104to use 105.Ar config_file 106instead of 107.Pa /etc/newsyslog.conf 108for its configuration file. 109.It Fl a Ar directory 110Specify a 111.Ar directory 112into which archived log files will be written. 113If a relative path is given, 114it is appended to the path of each log file 115and the resulting path is used as the directory 116into which the archived log for that log file will be written. 117If an absolute path is given, 118all archived logs are written into the given 119.Ar directory . 120If any component of the path 121.Ar directory 122does not exist, 123it will be created when 124.Nm 125is run. 126.It Fl d Ar directory 127Specify a 128.Ar directory 129which all log files will be relative to. 130To allow archiving of logs outside the root, the 131.Ar directory 132passed to the 133.Fl a 134option is unaffected. 135.It Fl v 136Place 137.Nm 138in verbose mode. 139In this mode it will print out each log and its 140reasons for either trimming that log or skipping it. 141.It Fl n 142Cause 143.Nm 144not to trim the logs, but to print out what it would do if this option 145were not specified. 146This option implies the 147.Fl r 148option. 149.It Fl r 150Remove the restriction that 151.Nm 152must be running as root. 153Of course, 154.Nm 155will not be able to send a HUP signal to 156.Xr syslogd 8 157so this option should only be used in debugging. 158.It Fl s 159Specify that 160.Nm 161should not send any signals to any daemon processes that it would 162normally signal when rotating a log file. 163For any log file which is rotated, this option will usually also 164mean the rotated log file will not be compressed if there is a 165daemon which would have been signalled without this option. 166However, this option is most likely to be useful when specified 167with the 168.Fl R 169option, and in that case the compression will be done. 170.It Fl t Ar timefmt 171If specified 172.Nm 173will create the 174.Dq rotated 175logfiles using the specified time format instead of the default 176sequential filenames. 177The filename used will be kept until it is deleted. 178The time format is described in the 179.Xr strftime 3 180manual page. 181If the 182.Ar timefmt 183argument is set to an empty string or the string 184.Dq DEFAULT , 185the default built in time format 186is used. 187If the 188.Ar timefmt 189string is changed the old files created using the previous time format 190will not be automatically removed (unless the new format is very 191similar to the old format). 192This is also the case when changing from sequential filenames to time 193based file names, and the other way around. 194The time format should contain at least year, month, day, and hour to 195make sure rotating of old logfiles can select the correct logfiles. 196.It Fl C 197If specified once, then 198.Nm 199will create any log files which do not exist, and which have the 200.Sy C 201flag specified in their config file entry. 202If specified multiple times, then 203.Nm 204will create all log files which do not already exist. 205If log files are given on the command-line, then the 206.Fl C 207or 208.Fl CC 209will only apply to those specific log files. 210.It Fl F 211Force 212.Nm 213to trim the logs, even if the trim conditions have not been met. 214This 215option is useful for diagnosing system problems by providing you with 216fresh logs that contain only the problems. 217.It Fl N 218Do not perform any rotations. 219This option is intended to be used with the 220.Fl C 221or 222.Fl CC 223options when creating log files is the only objective. 224.It Fl P 225Prevent further action if we should send signal but the 226.Dq pidfile 227is empty or does not exist. 228.It Fl R Ar tagname 229Specify that 230.Nm 231should rotate a given list of files, even if trim conditions are not 232met for those files. 233The 234.Ar tagname 235is only used in the messages written to the log files which are 236rotated. 237This differs from the 238.Fl F 239option in that one or more log files must also be specified, so that 240.Nm 241will only operate on those specific files. 242This option is mainly intended for the daemons or programs which write 243some log files, and want to trigger a rotate based on their own criteria. 244With this option they can execute 245.Nm 246to trigger the rotate when they want it to happen, and still give the 247system administrator a way to specify the rules of rotation (such as how 248many backup copies are kept, and what kind of compression is done). 249When a daemon does execute 250.Nm 251with the 252.Fl R 253option, it should make sure all of the log files are closed before 254calling 255.Nm , 256and then it should re-open the files after 257.Nm 258returns. 259Usually the calling process will also want to specify the 260.Fl s 261option, so 262.Nm 263will not send a signal to the very process which called it to force 264the rotate. 265Skipping the signal step will also mean that 266.Nm 267will return faster, since 268.Nm 269normally waits a few seconds after any signal that is sent. 270.It Fl S Ar pidfile 271Use 272.Ar pidfile 273as 274.Xr syslogd 8 Ns 's 275pidfile. 276.El 277.Pp 278If additional command line arguments are given, 279.Nm 280will only examine log files that match those arguments; otherwise, it 281will examine all files listed in the configuration file. 282.Sh FILES 283.Bl -tag -width /usr/local/etc/newsyslog.conf.d -compact 284.It Pa /etc/newsyslog.conf 285.Nm 286configuration file 287.It Pa /etc/newsyslog.conf.d 288By default each file in this directory ending in '.conf' and not beginning with 289a '.' will be included by the default 290.Pa newsyslog.conf . 291.It Pa /usr/local/etc/newsyslog.conf.d 292By default each file in this directory ending in '.conf' and not beginning with 293a '.' will be included by the default 294.Pa newsyslog.conf . 295.El 296.Sh COMPATIBILITY 297Previous versions of the 298.Nm 299utility used the dot (``.'') character to 300distinguish the group name. 301Beginning with 302.Fx 3.3 , 303this has been changed to a colon (``:'') character so that user and group 304names may contain the dot character. 305The dot (``.'') character is still 306accepted for backwards compatibility. 307.Sh SEE ALSO 308.Xr bzip2 1 , 309.Xr gzip 1 , 310.Xr xz 1 , 311.Xr zstd 1 , 312.Xr syslog 3 , 313.Xr newsyslog.conf 5 , 314.Xr chown 8 , 315.Xr syslogd 8 316.Sh HISTORY 317The 318.Nm 319utility originated from 320.Nx 321and first appeared in 322.Fx 2.2 . 323.Sh AUTHORS 324.An Theodore Ts'o , 325MIT Project Athena 326.Pp 327Copyright 1987, Massachusetts Institute of Technology 328