Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

logadm


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(1).


     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).  At the point when what would
     be the eleventh file is logged,logadm automatically  deletes
     the oldest version 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.conf file.
     The logadm command searches /etc/logadm.conf  for  lines  of
     the form logname options

     logname

         Identifies an entry in /etc/logadm.conf. This can  be  a
         name  or  the pathname of the log file. If you specify a
         log file, rather than a name, for this field, it must be
         a fully qualified pathname.


     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 over-
         ride those in /etc/logadm.conf.

         Log file names specified in /etc/logadm.conf can contain
         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  -Ssize. 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
     s -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 writing
         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 messages
         are  captured  by  cron  and  mailed to the owner of the
         crontab.

         This option is useful if 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 cmdto 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.


     -l

         Use local time rather  than  the  Coordinated  Universal
         Time  (UTC)  when naming rotated log files (see the dis-
         cussion of percent sequences in the  templates  supplied
         with the -t option).


     -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.


     -M cmd

         Use cmd to rename the log file. If the keyword $file  is
         specified,  it  is expanded to the name of the log file.
         Similarly, the keyword $nfile is  expanded  to  the  new
         name  of the log file. The $nfile keyword is only avail-
         able with commands provided with the  -M  option.  After
         the  command  completes, the log file is replaced by the
         rotate file. The default cmd is "/bin/mv $file $nfile".


     -n

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

         This option is useful for checking arguments before mak-
         ing 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.  There-
         fore,  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, h for
         hours,  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 rota-
         tion  period has passed. The format of timestamp matches
         the format generated by ctime(3C), with quotes around it
         to protect embedded spaces. timestamp is always recorded
         in the Coordinated Universal Time (UTC) timezone.


     -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 speci-
         fied 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  com-
         mand,  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 giga-
         bytes.


     -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 giga-
         bytes.


     -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,  January
             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 template results in a pathname with
         non-existent  directories, they are created as necessary
         when rotating the log file.

         If no -toption is specified,  the  default  template  is
         $file.$n.  Actual rotation of log files, where each ver-
         sion is shifted up until it expires is done using the $n
         keyword.  If  the  template does not contain the $n key-
         word, 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 pathname with
         special  characters  such  as  *  and  ? as supported 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 syn-
         tactically correct. If logname  is  not  specified,  all
         entries  in  the  configuration file are validated. If a
         logname argument is specified, the command validates the
         syntax  of  that  entry.  If  the  entry is found, it is
         printed and the exit value of the command is true.  Oth-
         erwise the exit value is false.


     -w entryname

         Write  an  entry  into  the  config   file   (that   is,
         /etc/logadm.conf)  that  corresponds to the current com-
         mand 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,  because
         it prevents syntax errors in that file. The entryname is
         an argument to an invocation of  logadm.  The  entryname
         might  be chosen as something easy to remember or it can
         be the pathname ofthe log file.

         If no log file name is  provided  on  a  logadm  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 result, keeping two copies of rotated
         log files:

           % logadm -C2 -w mylog /my/really/long/log/file/name
           % 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 Versios


     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.


        % 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:


       % 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.


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




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


        % 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.


        % 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:


       % 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.


       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), crontab(1),  csh(1),  gzip(1),
     cron(1M),  ctime(3C),  strftime(3C),  logadm.conf(4), attri-
     butes(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 might not be the expected behavior if an old log
     file has been modified since it was rotated.


     Note that, depending on log file sizes  and  number  of  log
     files, log file rotations can be very time-consuming.


     By default, logadm works  in  GMT.  Therefore,  all  entries
     written  to  the  /etc/logadm.conf file (see logadm.conf(4))
     will have a GMT timestamp. Users can use the  -l  option  to
     set logadm to local time.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments