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