logadm(1M)




NAME

     logadm - manage endlessly growing log files


SYNOPSIS

     logadm

     logadm [-options] logname...


DESCRIPTION

     logadm is a general log rotation tool that is  suitable  for
     running from cron(1M).

     Without arguments, logadm reads the  /etc/logadm.conf  file,
     and   for   every  entry  found  in  that  file  checks  the
     corresponding log file to see if it should be rotated. Typi-
     cally  this  check  is  done each morning by an entry in the
     root's crontab.

     If the logname argument is  specified,  logadm  renames  the
     corresponding  log  file by adding a suffix so that the most
     recent log file ends with .0 (that is, logfile.0), the  next
     most recent ends with .1 (that is, logfile.1), and so forth.
     By default, ten versions of old log files are kept (that is,
     logfile.0   through   logfile.9)  and  logadm  automatically
     deletes the oldest version  when  appropriate  to  keep  the
     count of files at ten.

     logadm takes a number of  options.  You  can  specify  these
     options on the command line or in the /etc/logadm.conffile .
     The logadm command searches /etc/logadm.conf  for  lines  of
     the form logname options

     logname
           Identifies the name of the entry in  /etc/logadm.conf,
           but  if  no log file name is given in that entry it is
           assumed that the logname is the same as the actual log
           file name.

     options
           Identifies command line options exactly as they  would
           be  entered  on the command line. This allows commonly
           used  log  rotation  policies  to  be  stored  in  the
           /etc/logadm.conf file. See EXAMPLES.

           If options are specified both in /etc/logadm.conf  and
           on  the  command  line,  those in the /etc/logadm.conf
           file are applied first. Therefore,  the  command  line
           options override those in /etc/logadm.conf.

           Log file names specified in /etc/logadm.conf may  con-
           tain  filename substitution characters such as * and ?
           that are supported by csh(1).

     Two options control when a log file is rotated. They are: -s
     size -p period.

     When using more than one of these options at a  time,  there
     is  an  implied and between them. This means that all condi-
     tions must be met before the log is rotated.

     If neither of these two options are specified,  the  default
     conditions  for  rotating a log file are: -s 1b -p 1w, which
     means the log file is only rotated if the size  is  non-zero
     and if at least 1 week has passed since the last time it was
     rotated.

     By specifying -p never as a rotation  condition,  any  other
     rotation  conditions  are ignored and logadm moves on to the
     expiration of old log files. By specifying -p now as a rota-
     tion condition, a log rotation is forced.

     Unless specified by  the  -o,  -g,  or  -m  options,  logadm
     replaces  the  log  file  (after renaming it) by creating an
     empty file whose owner, group ID, and permissions match  the
     original file.

     Three options control when old log files are expired: -A age
     -C  count -S size. These options expire the oldest log files
     until a particular condition  or  conditions  are  met.  For
     example, the combination -C 5 and the -S 10m options expires
     old log files until there are no more  than  5  of  the  and
     their  combined  disk usage is no more than 10 megabytes. If
     none of these options are specified, the default  expiration
     is  -C  10 which keeps ten old log files. If no files are to
     be expired, use -C 0 to prevent expiration by default.


OPTIONS

     The following options are supported:

     -a post_command
           Execute the post_command after renaming the log  file.
           post_command is passed to sh -c.

           Specify post_command as a  valid  shell  command.  Use
           quotes  to  protect  spaces or shell metacharacters in
           post_command.

           This option can be used to restart a  daemon  that  is
           writing  to the file. When rotating multiple logs with
           one logadm command, post_command is executed only once
           after  all  the logs are rotated, not once per rotated
           log.

     -A age
           Delete any versions that have not  been  modified  for
           the amount of time specified by age.

           Specify age as a number followed by an  h  (hours),  d
           (days), w(weeks), m (months), or y (years).

     -b pre_command
            Execute pre_command before  renaming  the  log  file.
           pre_command is passed to sh -c.

           Specify pre_command as  a  valid  shell  command.  Use
           quotes  to  protect  spaces or shell metacharacters in
           the pre_command.

           This option can be used to stop a daemon that is writ-
           ing  to the file. When rotating multiple logs with one
           logadm command,  pre_command  is  executed  only  once
           before  all the logs are rotated, not once per rotated
           log.

     -c    Rotate the log file by copying it and  truncating  the
           original  logfile to zero length, rather than renaming
           the file.

     -C count
           Delete the oldest versions until there  are  not  more
           than count files left.

           If no expire options (-A, -C, or -S) are specified, -C
           10  is the default. To prevent the default expire rule
           from being added automatically, specify -C 0 .

     -e mail_addr
           Send error messages by email to mail_addr.

           As logadm is typically run from cron(1M),  error  mes-
           sages  are captured by cron and mailed to the owner of
           the crontab.

           This option is useful  you  want  the  mail  regarding
           error messages to go to another address instead. If no
           errors are encountered, no mail message is generated.

     -E cmd
           Execute cmd to expire the file, rather  than  deleting
           the old log file to expire it.

           cmd is passed it to sh  -c.  The  file  is  considered
           expired  after  cmd  completes. If the old log file is
           not removed or renamed by the cmd, logadm considers it
           for  expiration  the  next  time  that  it runs on the
           specified log file. If present, the keyword  $file  is
           expanded  in the specified cmd to the name of the file
           being expired.

           This option is useful for tasks such  as  mailing  old
           log  files to administrators, or copying old log files
           to long term storage.

     -f conf_file
           Use conf_file instead of /etc/logadm.conf.

           This option allows non-root users to  keep  their  own
           logadm configuration files.

     -g group
           Create a new empty  file  with  the  ID  specified  by
           group,  instead  of preserving the group ID of the log
           file.

           Specify group by name  or  by  numeric  group  ID,  as
           accepted by chgrp(1).

           This option requires the ability to change file  group
           ownership using the chgrp(1) command.

     -h    Print a help message that describes logadm's options.

     -m mode
            Create a new empty file with the  mode  specified  by
           mode, instead of preserving the mode of the log file.

           Specify mode in any  form  that  is  accepted  by  the
           chmod(1) command.

     -n    Print the actions that the logadm command will perform
           without actually performing them.

           This option is useful for  checking  arguments  before
           making any changes to the system.

            It is important to remember, however, that since  log
           rotating  actions  are  only printed with this option,
           logadm might not find files that need expiring, but if
           run  without  the  -n  logadm might create a file that
           needs expiring by performing the log rotating actions.
           Therefore,  if you see no files being expired with the
           -n option, files still might be expired without it.

     -N    Prevent an error message if the specified logfile does
           not  exist. Normally, logadm produces an error message
           if the log file is not found. With -N, if the log file
           doesn't  exist logadm moves on to the expire rules (if
           any) and then to the next log file (if  any),  without
           creating the empty replacement log file.

     -o owner
           Create the new  empty  file  with  owner,  instead  of
           preserving the owner of the log file.

           Specify owner in any form  that  is  accepted  by  the
           chown(1) command.

     -p period
            Rotate a log file after  the  specified  time  period
           (period) .

           Specify period as a number followed by d for  days,  w
           for  weeks,  m  for  months  (really 30 days) or y for
           years. There are also two special values  for  period:
           now  and  never.  -p now forces log rotation. -p never
           forces no log rotation.

     -P timestamp
           Used by logadm to record the last  time  the  log  was
           rotated in /etc/logadm.conf.

           This option uses timestamp to  determine  if  the  log
           rotation  period  has  passed. The format of timestamp
           matches the format generated by ctime(3C), with quotes
           around it to protect embedded spaces.

     -r    Remove any entries corresponding to the specified log-
           name from the /etc/logadm.conf.

     -R  cmd
           Run the cmd when an old log file is created by  a  log
           rotation.  If  the  keyword  $file  is embedded in the
           specified command, it is expanded to the name  of  the
           old log file just created by log rotation.

           This option is useful for processing log file contents
           after  rotating the log. cmd is executed by passing it
           to sh -c. When rotating multiple logs with one  logadm
           command, the command supplied with -R is executed once
           every time a log is rotated. This is useful for  post-
           processing  a  log file (that is, sorting it, removing
           uninteresting lines, etc.). The -a option is a  better
           choice for restarting daemons after log rotation.

     -s size
           Rotate the log file only if its size is  greater  than
           or equal to size.

           Specify size as a number followed by the letter b  for
           bytes,  k  for  kilobytes,  m  for megabytes, or g for
           gigabytes.

     -S size
           Delete the oldest versions until the total disk  space
           used  by  the old log files is less than the specified
           size.

           Specify size as a number followed by the letter b  for
           bytes,  k  for  kilobytes,  m  for megabytes, or g for
           gigabytes.

     -t template
           Specify the template to use when renaming log files.

           template   can   be   a   simple   name,    such    as
           /var/adm/oldfile,  or  it can contain special keywords
           which are expanded by  logadm  and  are  in  the  form
           $word. Allowed sequences are:

           $file The full path name of the file to be rotated

           $dirname
                 The directory of the file to be rotated

           $basename
                 The log file name, without the  directory name

           $n    The version number, 0 is most recent, 1 is  next
                 most recent, and so forth

           $N    The same as $n, but starts at 1 instead of zero

           $secs The number of seconds since 00:00:00 UTC,  Janu-
                 ary 1,1970

           $nodename
                 Expands to the output of uname -n

           $platform
                 Expands to the output of uname -i

           $isa  Expands to the output of uname -p

           $release
                 Expands to the output of uname -r

           $machine
                 Expands to the output of uname -m

           $domain
                 Expands to the output of domainname

     To actually have the dollar sign character in the file name,
     use  $$.  Any  percent sequences allowed by strftime(3C) are
     also allowed, for example, %d expands  to  the  day  of  the
     month. To actually have a percent sign character in the file
     name,  use  %%.  Both  dollar-sign  keywords   and   percent
     sequences  can  appear anywhere in the template. If the tem-
     plate results in a pathname with  non-existent  directories,
     they are created as necessary when rotating the log file.

           If no -t option is specified, the default template  is
           $file.$n.  Actual  rotation  of  log files, where each
           version is shifted up until it expires is  done  using
           the  $n  keyword. If the template does not contain the
           $n keyword, the log file is simply renamed to the  new
           name and then the expire rules, if any, are applied.

     -T pattern
           Normally logadm looks for a list of old log  files  by
           turning  the  template  (specified with the -t option)
           into a pattern and finding existing files whose  names
           match  that  pattern.   The -T option causes the given
           pattern to be used instead.

           This option is useful if another program fiddles  with
           the  old  log  file names, like a cron job to compress
           them over time. The pattern is in the form of a  path-
           name  with  special characters such as * and ? as sup-
           ported by csh(1) filename substitution.

     -v    Print information about the actions being executed  in
           verbose mode.

     -V    Validate the configuration file.

           This option validates that an entry for the  specified
           logname  exists  in  the  /etc/logadm.conf file and is
           syntactically correct. If logname  is  not  specified,
           all  entries  in the configuration file are validated.
           If a logname argument is specified, the command  vali-
           dates the syntax of that entry. If the entry is found,
           it is printed and the exit value  of  the  command  is
           true. Otherwise the exit value is false.

     -w entryname
           Write  an  entry  into  the  config  file  (that   is,
           /etc/logadm.conf)  which  corresponds  to  the current
           command line arguments. If an  entry  already  existed
           for the specified entryname, it is removed first. This
           is the preferred method for updating  /etc/logadm.conf
           since  using  it  prevents syntax errors in that file.
           The  entryname  is  the   name   of   the   entry   in
           /etc/logadm.conf,  and  that  name  can be used as the
           "logname" argument to future calls to logadm  to  take
           advantage  of  that entry. The entryname can be chosen
           to be something that is easy to specify, or it can  be
           the  actual log file name. If no log file name is pro-
           vided on the command line, the entry name  is  assumed
           to  be the same as the log file name. For example, the
           following two lines achieve the  same  thing,  keeping
           two copies of rotated log files, but the first example
           names the entry something easier to enter on the  com-
           mand line:

           example% logadm -C2 -w mylog /my/really/long/log/file/name
           example% logadm -C2 -w /my/really/long/log/file/name

     -z count
           Compress old log files as they are created.  count  of
           the  most  recent  log  files  are  left uncompressed,
           therefore making the count most recent files easier to
           peruse. Use count of zero to compress all old logs.

           The compression is done with gzip(1) and the resulting
           log file has the suffix of .gz.


OPERANDS

     The following operands are supported:

     logname
           Identifies the name of the entry in  /etc/logadm.conf.
           If  the  log  file  name  is  specified in the logname
           field, it is assumed that logname is the same  as  the
           actual log file name.


EXAMPLES

     Example 1: Rotating a File and Keeping Previous Versions

     The following example rotates the /var/adm/exacct/proc file,
     keeping  ten  previous  versions  in  /var/adm/exacct/proc.0
     through /var/adm/exacct/proc.9.

     Tell logadm to copy the file and truncate it.

     example% logadm -c /var/adm/exacct/proc

     Example 2: Rotating syslog

     The following example rotates syslog  and  keeps  eight  log
     files.  Old  log files are put in the directory /var/oldlogs
     instead of /var/log:

     example% logadm -C8 -t'/var/oldlogs/syslog.$n' /var/log/syslog

     Example 3: Rotating /var/adm/sulog and Expiring Based on Age

     The following entry in the /etc/logadm.conf file rotates the
     /var/adm/sulog  file  and  expires  any copies older than 30
     days.

     /var/adm/sulog -A 30d

     Example 4: Rotating Files and Expiring Based on Disk Usage

     The following entry in the /etc/logadm.conf file rotates the
     /var/adm/sulog file and expires old log files when more than
     100 megabytes are used by the sum of  all  the  rotated  log
     files.

     /var/adm/sulog -S 100m

     Example 5: Creating an Entry that Stores the Logfile Name

     This example creates an entry storing the log file name  and
     the fact that we want to keep 20 copies in /etc/logadm.conf,
     but the -p never means the entry is ignored  by  the  normal
     logadm run from root's crontab every morning.

     example% logadm -w locallog /usr/local/logfile -C20 -p never

     Use the following entry on the command line to override  the
     -p never option:

     example% logadm -p now locallog

     Example 6: Rotating the apache Error and Access Logs

     The following example rotates the apache  error  and  access
     logs  monthly  to filenames based on current year and month.
     It keeps the 24 most recent copies and tells apache to  res-
     tart after renaming the logs.

     This command is run once, and since the -w option is  speci-
     fied,  an  entry  is  made in /etc/logadm.conf so the apache
     logs are rotated from now on.

     example% logadm -w apache -p 1m -C 24\
          -t '/var/apache/old-logs/$basename.%Y-%m'\
          -a '/usr/apache/bin/apachectl graceful'\
          '/var/apache/logs/*{access,error}_log'

     This example also illustrates that the entry  name  supplied
     with  the -w option doesn't have to match the log file name.
     In this example, the entry name is apache and once the  line
     has been run, the entry in /etc/logadm.conf can be forced to
     run by executing the following command:

     example% logadm -p now apache

     Because the expression matching the apache  log  file  names
     was   enclosed  in  quotes,  the  expression  is  stored  in
     /etc/logadm.conf, rather than the  list  of  files  that  it
     expands  to. This means that each time logadm runs from cron
     it expands that expression and checks all the log  files  in
     the resulting list to see if they need rotating.

     The following command  is  an  example  without  the  quotes
     around  the  log name expression. The shell expands the last
     argument into a list of log files that exist at the time the
     command  is entered, and writes an entry to /etc/logadm.conf
     that rotates the files.

     example% logadm -w apache /var/apache/logs/*_log


FILES

     /etc/logadm.conf
           configuration file for logadm command


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWcsu                     |
    |_____________________________|_____________________________|


SEE ALSO

     chgrp(1), chmod(1),  chown(1),  csh(1),  gzip(1),  cron(1M),
     ctime(3C), strftime(3C), logadm.conf(4), attributes(5)


NOTES

     When logadm applies expire conditions (supplied by  the  -A,
     -C,  and  -S  options),  it deletes files, the oldest first,
     until the conditions are satisfied. If the template used for
     naming  the  old  logs  contained $n or $N, logadm picks the
     highest value of $n or $N found in the old  log  file  names
     first.  If  the template used is something else, logadm uses
     the modification time to determine  which  files  to  expire
     first.  This  may not be the expected behavior if an old log
     file has been modified since it was rotated.


Man(1) output converted with man2html