logadm man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

LOGADM(1M)							    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. Typically 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). 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 com‐
	   mand 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  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 conditions	 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 con‐
       ditions	are  ignored  and logadm moves on to the expiration of old log
       files. By specifying -p now as a rotation 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 pro‐
	   tect 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_com‐
	   mand	 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  log‐
	   file 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 auto‐
	   matically, 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  cap‐
	   tured 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 configu‐
	   ration 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  discussion  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 key‐
	   word	 is  only available 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  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, h for hours, w
	   for weeks, m for months (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.	 time‐
	   stamp is always recorded in the Coordinated	Universal  Time	 (UTC)
	   timezone.

       -r

	   Remove  any entries corresponding to the specified logname 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	 rota‐
	   tion.

	   This option is useful for processing log file contents after rotat‐
	   ing 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 uninter‐
	   esting lines, etc.). The -a option is a better choice for  restart‐
	   ing 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:

	   $basename

	       The log file name, without the directory name

	   $dirname

	       The directory of the file to be rotated

	   $domain

	       Expands to the output of domainname

	   $file

	       The full path name of the file to be rotated

	   $isa

	       Expands to the output of uname -p

	   $machine

	       Expands to the output of uname -m

	   $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

	   $nodename

	       Expands to the output of uname -n

	   $platform

	       Expands to the output of uname -i

	   $release

	       Expands to the output of uname -r

	   $secs

	       The number of seconds since 00:00:00 UTC, January 1,1970

	   $zonename

	       Expands to the output of zonename(1).

	   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 directo‐
	   ries, 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 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 syntactically correct.
	   If logname is not specified, all entries in the configuration  file
	   are validated. If a logname argument is specified, the command val‐
	   idates 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)
	   that 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, because
	   it prevents syntax errors.  The entryname  is  an  argument	to  an
	   invocation  of logadm.  entryname might be chosen as something easy
	   to remember or it can be the pathname of the log file. If  a	 path‐
	   name,  rather  than	a  name	 is used, it must be a fully qualified
	   pathname.

	   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 thing, 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 after all other commands have been executed.
	   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.

	  % 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 restart after renaming the logs.

       This  command  is  run  once,  and since the -w option is specified, 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  com‐
       mand:

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Evolving	      │
       └────────────────────┴─────────────────┘

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.

       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.

				 May 23, 2007			    LOGADM(1M)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net