1.\" This file contains changes from the Open Software Foundation. 2.\" 3.\" from: @(#)newsyslog.8 4.\" $FreeBSD: head/usr.sbin/newsyslog/newsyslog.8 318960 2017-05-26 16:36:30Z dab $ 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 29, 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 is 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 space. 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 f Ar config_file 83Instruct 84.Nm 85to use 86.Ar config_file 87instead of 88.Pa /etc/newsyslog.conf 89for its configuration file. 90.It Fl a Ar directory 91Specify a 92.Ar directory 93into which archived log files will be written. 94If a relative path is given, 95it is appended to the path of each log file 96and the resulting path is used as the directory 97into which the archived log for that log file will be written. 98If an absolute path is given, 99all archived logs are written into the given 100.Ar directory . 101If any component of the path 102.Ar directory 103does not exist, 104it will be created when 105.Nm 106is run. 107.It Fl d Ar directory 108Specify a 109.Ar directory 110which all log files will be relative to. 111To allow archiving of logs outside the root, the 112.Ar directory 113passed to the 114.Fl a 115option is unaffected. 116.It Fl v 117Place 118.Nm 119in verbose mode. 120In this mode it will print out each log and its 121reasons for either trimming that log or skipping it. 122.It Fl n 123Cause 124.Nm 125not to trim the logs, but to print out what it would do if this option 126were not specified. 127This option implies the 128.Fl r 129option. 130.It Fl r 131Remove the restriction that 132.Nm 133must be running as root. 134Of course, 135.Nm 136will not be able to send a HUP signal to 137.Xr syslogd 8 138so this option should only be used in debugging. 139.It Fl s 140Specify that 141.Nm 142should not send any signals to any daemon processes that it would 143normally signal when rotating a log file. 144For any log file which is rotated, this option will usually also 145mean the rotated log file will not be compressed if there is a 146daemon which would have been signalled without this option. 147However, this option is most likely to be useful when specified 148with the 149.Fl R 150option, and in that case the compression will be done. 151.It Fl t Ar timefmt 152If specified 153.Nm 154will create the 155.Dq rotated 156logfiles using the specified time format instead of the default 157sequential filenames. 158The filename used will be kept until it is deleted. 159The time format is described in the 160.Xr strftime 3 161manual page. 162If the 163.Ar timefmt 164argument is set to an empty string or the string 165.Dq DEFAULT , 166the default built in time format 167is used. 168If the 169.Ar timefmt 170string is changed the old files created using the previous time format 171will not be automatically removed (unless the new format is very 172similar to the old format). 173This is also the case when changing from sequential filenames to time 174based file names, and the other way around. 175The time format should contain at least year, month, day, and hour to 176make sure rotating of old logfiles can select the correct logfiles. 177.It Fl C 178If specified once, then 179.Nm 180will create any log files which do not exist, and which have the 181.Sy C 182flag specified in their config file entry. 183If specified multiple times, then 184.Nm 185will create all log files which do not already exist. 186If log files are given on the command-line, then the 187.Fl C 188or 189.Fl CC 190will only apply to those specific log files. 191.It Fl F 192Force 193.Nm 194to trim the logs, even if the trim conditions have not been met. 195This option 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 ".Pa /usr/local/etc/newsyslog.conf.d" -compact 264.It Pa /etc/newsyslog.conf 265.Nm 266configuration file 267.\".It Pa /etc/newsyslog.conf.d 268.\"Each file in this directory will be included by the default 269.\".Pa newsyslog.conf . 270.It Pa /usr/local/etc/newsyslog.conf.d 271Each file in this directory will be included by the default 272.Pa newsyslog.conf . 273.El 274.Sh COMPATIBILITY 275Previous versions of the 276.Nm 277utility used the dot (``.'') character to 278distinguish the group name. 279Beginning with 280.Fx 3.3 , 281this has been changed to a colon (``:'') character so that user and group 282names may contain the dot character. 283The dot (``.'') character is still accepted for backwards compatibility. 284.Sh SEE ALSO 285.Xr bzip2 1 , 286.Xr gzip 1 , 287.Xr xz 1 , 288.Xr zstd 1 , 289.Xr syslog 3 , 290.Xr newsyslog.conf 5 , 291.Xr chown 8 , 292.Xr syslogd 8 293.Sh HISTORY 294The 295.Nm 296utility originated from 297.Nx 298and first appeared in 299.Fx 2.2 . 300.Sh AUTHORS 301.An Theodore Ts'o , 302MIT Project Athena 303.Pp 304Copyright 1987, Massachusetts Institute of Technology 305.Sh BUGS 306Does not yet automatically read the logs to find security breaches. 307