System Administration Commands 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). 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.
SunOS 5.11 Last change: 23 May 2007 1
System Administration Commands logadm(1M)
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 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 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:
SunOS 5.11 Last change: 23 May 2007 2
System Administration Commands logadm(1M)
-a postcommand
Execute the postcommand after renaming the log file.
postcommand is passed to sh -c.
Specify postcommand as a valid shell command. Use
quotes to protect spaces or shell metacharacters in
postcommand.
This option can be used to restart a daemon that is
writing to the file. When rotating multiple logs with
one logadm command, postcommand 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 precommand
Execute precommand before renaming the log file.
precommand is passed to sh -c.
Specify precommand as a valid shell command. Use quotes
to protect spaces or shell metacharacters in the
precommand.
This option can be used to stop a daemon that is writing
to the file. When rotating multiple logs with one logadm
command, precommand 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.
SunOS 5.11 Last change: 23 May 2007 3
System Administration Commands logadm(1M)
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 mailaddr
Send error messages by email to mailaddr.
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 conffile
Use conffile 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
SunOS 5.11 Last change: 23 May 2007 4
System Administration Commands logadm(1M)
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.
SunOS 5.11 Last change: 23 May 2007 5
System Administration Commands logadm(1M)
-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 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
SunOS 5.11 Last change: 23 May 2007 6
System Administration Commands logadm(1M)
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:
$basename
The log file name, without the directory name
$dirname
The directory of the file to be rotated
SunOS 5.11 Last change: 23 May 2007 7
System Administration Commands logadm(1M)
$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
SunOS 5.11 Last change: 23 May 2007 8
System Administration Commands logadm(1M)
$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 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 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
SunOS 5.11 Last change: 23 May 2007 9
System Administration Commands logadm(1M)
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. 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 pathname, 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.
SunOS 5.11 Last change: 23 May 2007 10
System Administration Commands logadm(1M)
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
SunOS 5.11 Last change: 23 May 2007 11
System Administration Commands logadm(1M)
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:
SunOS 5.11 Last change: 23 May 2007 12
System Administration Commands logadm(1M)
% 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
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWcsu
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
SunOS 5.11 Last change: 23 May 2007 13
System Administration Commands logadm(1M)
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.
SunOS 5.11 Last change: 23 May 2007 14
|
