LOGADM(8) Maintenance Commands and Procedures LOGADM(8)
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(8).
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 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 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
conditions 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 of the
-C 5 and
-S 10m options expires old log files until there are no more than 5
of them
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 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(8), 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
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.
-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 keyword 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.
timestamp 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 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:
$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 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 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 validates
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 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.
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 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(7) 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),
ctime(3C),
strftime(3C),
logadm.conf(5),
attributes(7),
cron(8)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(5)) will have a
GMT timestamp.
Users can use the
-l option to set
logadm to local time.
June 20, 2021
LOGADM(8)