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