usr.sbin/newsyslog/newsyslog.8

   1 .\" This file contains changes from the Open Software Foundation.
   2 .\"
   3 .\"     from: @(#)newsyslog.8
   4 .\" $FreeBSD: src/usr.sbin/newsyslog/newsyslog.8,v 1.51 2005/06/14 12:26:35 ru Exp $
   5 .\" $DragonFly: src/usr.sbin/newsyslog/newsyslog.8,v 1.4 2007/05/12 08:52:00 swildner Exp $
   6 .\"
   7 .\" Copyright 1988, 1989 by the Massachusetts Institute of Technology
   8 .\"
   9 .\" Permission to use, copy, modify, and distribute this software
  10 .\" and its documentation for any purpose and without fee is
  11 .\" hereby granted, provided that the above copyright notice
  12 .\" appear in all copies and that both that copyright notice and
  13 .\" this permission notice appear in supporting documentation,
  14 .\" and that the names of M.I.T. and the M.I.T. S.I.P.B. not be
  15 .\" used in advertising or publicity pertaining to distribution
  16 .\" of the software without specific, written prior permission.
  17 .\" M.I.T. and the M.I.T. S.I.P.B. make no representations about
  18 .\" the suitability of this software for any purpose.  It is
  19 .\" provided "as is" without express or implied warranty.
  20 .\"
  21 .Dd May 2, 2007
  22 .Dt NEWSYSLOG 8
  23 .Os
  24 .Sh NAME
  25 .Nm newsyslog
  26 .Nd maintain system log files to manageable sizes
  27 .Sh SYNOPSIS
  28 .Nm
  29 .Op Fl CFNnrsv
  30 .Op Fl R Ar tagname
  31 .Op Fl a Ar directory
  32 .Op Fl d Ar directory
  33 .Op Fl f Ar config_file
  34 .Op Ar
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 utility should be scheduled to run periodically by
  39 .Xr cron 8 .
  40 When it is executed it archives log files if necessary.
  41 If a log file is determined to require archiving,
  42 .Nm
  43 rearranges the files so that
  44 .Dq Va logfile
  45 is empty,
  46 .Dq Va logfile Ns Li \&.0
  47 has
  48 the last period's logs in it,
  49 .Dq Va logfile Ns Li \&.1
  50 has the next to last
  51 period's logs in it, and so on, up to a user-specified number of
  52 archived logs.
  53 Optionally the archived logs can be compressed to save space.
  54 .Pp
  55 A log can be archived for three reasons:
  56 .Bl -enum -offset indent
  57 .It
  58 It is larger than the configured size (in kilobytes).
  59 .It
  60 A configured number of hours have elapsed since the log was last
  61 archived.
  62 .It
  63 This is the specific configured hour for rotation of the log.
  64 .El
  65 .Pp
  66 The granularity of
  67 .Nm
  68 is dependent on how often it is scheduled to run by
  69 .Xr cron 8 .
  70 Since the program is quite fast, it may be scheduled to run every hour
  71 without any ill effects,
  72 and mode three (above) assumes that this is so.
  73 .Sh OPTIONS
  74 The following options can be used with
  75 .Nm :
  76 .Bl -tag -width indent
  77 .It Fl f Ar config_file
  78 Instruct
  79 .Nm
  80 to use
  81 .Ar config_file
  82 instead of
  83 .Pa /etc/newsyslog.conf
  84 for its configuration file.
  85 .It Fl a Ar directory
  86 Specify a
  87 .Ar directory
  88 into which archived log files will be written.
  89 If a relative path is given,
  90 it is appended to the path of each log file
  91 and the resulting path is used as the directory
  92 into which the archived log for that log file will be written.
  93 If an absolute path is given,
  94 all archived logs are written into the given
  95 .Ar directory .
  96 If any component of the path
  97 .Ar directory
  98 does not exist,
  99 it will be created when
 100 .Nm
 101 is run.
 102 .It Fl d Ar directory
 103 Specify a
 104 .Ar directory
 105 which all log files will be relative to.
 106 To allow archiving of logs outside the root, the
 107 .Ar directory
 108 passed to the
 109 .Fl a
 110 option is unaffected.
 111 .It Fl v
 112 Place
 113 .Nm
 114 in verbose mode.
 115 In this mode it will print out each log and its
 116 reasons for either trimming that log or skipping it.
 117 .It Fl n
 118 Cause
 119 .Nm
 120 not to trim the logs, but to print out what it would do if this option
 121 were not specified.
 122 .It Fl r
 123 Remove the restriction that
 124 .Nm
 125 must be running as root.
 126 Of course,
 127 .Nm
 128 will not be able to send a HUP signal to
 129 .Xr syslogd 8
 130 so this option should only be used in debugging.
 131 .It Fl s
 132 Specify that
 133 .Nm
 134 should not send any signals to any daemon processes that it would
 135 normally signal when rotating a log file.
 136 For any log file which is rotated, this option will usually also
 137 mean the rotated log file will not be compressed if there is a
 138 daemon which would have been signalled without this option.
 139 However, this option is most likely to be useful when specified
 140 with the
 141 .Fl R
 142 option, and in that case the compression will be done.
 143 .It Fl C
 144 If specified once, then
 145 .Nm
 146 will create any log files which do not exist, and which have the
 147 .Sy C
 148 flag specified in their config file entry.
 149 If specified multiple times, then
 150 .Nm
 151 will create all log files which do not already exist.
 152 If log files are given on the command-line, then the
 153 .Fl C
 154 or
 155 .Fl CC
 156 will only apply to those specific log files.
 157 .It Fl F
 158 Force
 159 .Nm
 160 to trim the logs, even if the trim conditions have not been met.
 161 This option is useful for diagnosing system problems by providing you with
 162 fresh logs that contain only the problems.
 163 .It Fl N
 164 Do not perform any rotations.
 165 This option is intended to be used with the
 166 .Fl C
 167 or
 168 .Fl CC
 169 options when creating log files is the only objective.
 170 .It Fl R Ar tagname
 171 Specify that
 172 .Nm
 173 should rotate a given list of files, even if trim conditions are not
 174 met for those files.
 175 The
 176 .Ar tagname
 177 is only used in the messages written to the log files which are
 178 rotated.
 179 This differs from the
 180 .Fl F
 181 option in that one or more log files must also be specified, so that
 182 .Nm
 183 will only operate on those specific files.
 184 This option is mainly intended for the daemons or programs which write
 185 some log files, and want to trigger a rotate based on their own criteria.
 186 With this option they can execute
 187 .Nm
 188 to trigger the rotate when they want it to happen, and still give the
 189 system administrator a way to specify the rules of rotation (such as how
 190 many backup copies are kept, and what kind of compression is done).
 191 When a daemon does execute
 192 .Nm
 193 with the
 194 .Fl R
 195 option, it should make sure all of the log files are closed before
 196 calling
 197 .Nm ,
 198 and then it should re-open the files after
 199 .Nm
 200 returns.
 201 Usually the calling process will also want to specify the
 202 .Fl s
 203 option, so
 204 .Nm
 205 will not send a signal to the very process which called it to force
 206 the rotate.
 207 Skipping the signal step will also mean that
 208 .Nm
 209 will return faster, since
 210 .Nm
 211 normally waits a few seconds after any signal that is sent.
 212 .El
 213 .Pp
 214 If additional command line arguments are given,
 215 .Nm
 216 will only examine log files that match those arguments; otherwise, it
 217 will examine all files listed in the configuration file.
 218 .Sh FILES
 219 .Bl -tag -width /etc/newsyslog.confxxxx -compact
 220 .It Pa /etc/newsyslog.conf
 221 .Nm
 222 configuration file
 223 .El
 224 .Sh COMPATIBILITY
 225 Previous versions of the
 226 .Nm
 227 utility used the dot (``.'') character to
 228 distinguish the group name.
 229 Beginning with
 230 .Fx 3.3 ,
 231 this has been changed to a colon (``:'') character so that user and group
 232 names may contain the dot character.
 233 The dot (``.'') character is still accepted for backwards compatibility.
 234 .Sh "SEE ALSO"
 235 .Xr bzip2 1 ,
 236 .Xr gzip 1 ,
 237 .Xr syslog 3 ,
 238 .Xr newsyslog.conf 5 ,
 239 .Xr chown 8 ,
 240 .Xr syslogd 8
 241 .Sh HISTORY
 242 The
 243 .Nm
 244 utility originated from
 245 .Nx
 246 and first appeared in
 247 .Fx 2.2 .
 248 .Sh AUTHORS
 249 .An Theodore Ts'o ,
 250 MIT Project Athena
 251 .Pp
 252 Copyright 1987, Massachusetts Institute of Technology
 253 .Sh BUGS
 254 Does not yet automatically read the logs to find security breaches.