			C H K L O G S   
			 Version 1.7

Introduction
------------

Sooner or later every system admininistrator has to check and purge-if
necessary-the system logs. These system logs are created by programs
such as cron, init, list managers, mail programs, news, uucp, etc. These
logs always grow, some faster than others but in the end they end up
using precious disk space. To avoid running out of disk space these
system logs have to be trimmed or purged when the information they
contain is no longer necessary. When archiving logs (supported
by the script) there is also a risk to waste too much disk space with
too many (read old) archived logs, to prevent this a shuffling 
mechanism is used.

The location of the logs vary from system to system, and sometimes
the person installing the distribution has little knowledge about
the location (or even existence!) of these log files. This program
can either be part of the system administrator's tool set, or in
the case of newbies the program can be installed in such a way that
he receives the proper warnings when necessary.

In summary, a relatively small and simple implementation in 
a single language.

What you will find here
-----------------------

chklogs		The Perl script	(v1.7)
chklogs.lsm	Linux Software Map entry (v1.7)
chklogs.txt	This document (v1.5)
chklogs.8	Manual page	(v1.3)
chklogs.conf	A sample Log Index (configuration) file (used in my system)

What's new in this version
--------------------------

* Changed the way the new logs are created after archival. It seems some
  programs keep the logs open and got confused when chklogs did the trick.
  Now a copy is first made and then a truncate to zero. The `touch' 
  program is no longer needed.

* Eliminated the warning on stdout (or the separate mail) when `ls' 
  does not find any file matching the file spec. Redirect stderr.

* When the archive already existed the script was reporting that it had
  archived it when it had really done nothing. Proper message is 
  generated now.

* When the new log is created the correct permissions AND ownership
  are maintained. Previously, by omission, it was only keeping the
  ownership.

- chklogs version number added to manual page in case some find the
  date not to be sufficient enough.

- slight change in the header of the -c option, now it indicates the
  basename of the log too because sometimes there are several log types
  in the same directory (for example smail configurations)

- The test (-t) now reports properly for truncate.

* It is now possible to have comment lines in the configuration (index)
  file. Any line starting with # in the first column is considered a comment.

* The name and location of the configuration file have changed, this 
  became /etc/chklogs.conf instead of /home/root/.log

* Added `execute' action! so now you can add your own handler, this is
  very useful if you want to perform statistics on a log before archiving
  for example. In which case your handler must then take care of the
  archiving too! 

The Log Index file
------------------

First you need to know the location of the system logs that are
active in your system/distribution. You also need to assign to
each of these logs a maximum allowable size, that is a size after
which the system administrator better purge them in case (s)he
forgot. Additionally the default action must be specified, this
can be:
	archive	   Archive the file (and shuffle) by GNUzipping it.
	truncate   Truncate the file to zero length
	execute	   Execute an external program

Also the maximum number of archived log files per log can be 
specified for fine tuning. If blank or zero de default from the
script (maxlogs) is used. For truncate no extra inforamation/parameter
is needed. Execute needs the name of the program to be executed. Note
that there is no need for a 'warn' action because there is already a
`-w'  (warn) command line option.

The information is kept in a plain file containing the full path (and name)
of the log in the 1st column. The maximum size allowed for the given
log goes in the 2nd column, the default action in the 3rd and in the
4th column the maximum number of archives per log file before removing
the oldest one. The location of the Index File is kept in $logf
and contains a series of records for each of the logs to be examined.

A sample log index (configuration) file would look like this:

# This is a comment line
/var/spool/uucp/Log		  5000	truncate	
/var/spool/syslog/syslog	 10000	archive     3
# Do statistics on the fly
/var/spool/syslog/ppp.log	  9788	execute	    /usr/local/bin/ppp-report
/var/log/news/nntpsend.log	  2800	archive	    7

This configuration file is now kept in /etc/chklogs.conf although
some administrators would probably choose /var/adm, /usr/adm or the like.

Configuration
-------------

You may need or want to modify the following variables in the script to
suit it to your system:

$zipper		The command used to invoke the program that will compress
		the offending log. Defaults to `/bin/gzip'.
$zipext		The extension given to the compressed file by the $zipper.
		Defaults to `gz'.
$logf		The Log Index file. Defaults to `/home/root/.log'.
$admin		The system administrator's account, mail will be sent
		to this address. Defaults to `root'.
$mailer		The actual mailer program and any options. Defaults
		to `/usr/sbin/sendmail -ep -i'.
$maxlogs	Shuffling. Default Maximum nr. of logs allowed (per type)
		before the oldest is removed in case the index file has
		an illegal (or zero) value.
$a_archive	The string literal that denotes the ARCHIVE action.
		Defaults to `archive'
$a_truncate	The string literal that denotes the TRUNCATE action.
		Defaults to `truncate'
$a_execute	The string literal that denotes the EXECUTE action.
		Defaults to `execute'
$syslogF	Location of syslog PID file. Default is `/var/run/syslog.pid'

How to Use chklogs
------------------

Chklogs could be used at the system administrator's discretion, or
by creating a cron entry or by having it execute at boot time. The
first two seem more appropriate.

Chklogs will compare the maximum allowable sizes of each log -as 
given in the Log Index- against the actual size of the log file
being examined. Then a report is produced that will include as
part of the header:
	a) The location of the Log Index file
	b) The size reporting method (byte)
	c) Column headings for the contents of the report
	d) The generic name of archived logs if archiving is 
	   enabled.

The syntax of the command is as follows:

	chklogs 
	chklogs -t
	chklogs -c
	chklogs [ -m | -w | -a ]

In the first form (no options) chklogs will process all the logs
according to the default action specified in the Index File and a
report will be produced on stdout. This reports includes the 
following for *each* of the examined system logs:

	1) The fully qualified filename of the system logfile
	2) The current size of the log
	3) The maximum allowed size as specified in the Log Index file
	4) Either Action taken (archived, truncated, execute, ok) or
	   action to be taken (archive!, truncate!, execute, ok)

If a log has grown out of the maximum specified size, the action column
will show the action taken by the program, that is whether it was 
archived, truncated or the execution of an external program.

When an external program is used (execute action) this program should
expect one command line parameter because chklogs will pass the fully
qualified file name to this external program.

The second form (-t option) will parse the Log Index file and produce
a listing with the same header as above but with the following info
per log file:

	1) Fully qualified filename of the system log
	2) Maximum allowed size
	3) Action to be taken (shows "????" if unknown)
	4) The maximum number of archived logs for this logfile

The third form (-c option) makes use of the Log Index to give a 
listing (on stdout) of *all* log files (archived or not) that 
are present in the system. This option is useful to have a quick
overview of what (archived) logs are in the filesystem.

Both the -t and the -c options should not be used with any other
option. The rest of the options as explained below can be mixed
together to produce the desired results.

The -w option (WARN) goes through the index and checks all the logfiles
but it does not take any action. Instead it will report with the Action
column indicating `archive!' or `truncate!' to indicate the recipient 
that those actions (as suggested by the default) need to be taken.

The -a option (ARCHIVE) operates very much like the first form (no
options) except that if a logfile has a `truncate' for default 
action it will be overriden and an archive will be made instead. The
report will show the new action accordingly. The archives are only
made if and only if the logfile has grown past its size limit. An
archive means that the log will be first timestamped to indicate its
archival date on the filename and then compressed. So the archived 
logfile would be named like `syslog.951119.gz'. A new logfile of
size zero is also re-created with the appropriate permissions.

The -m option (MAIL) as the name indicates mails the report to the
$admin user instead of the standard output. This is mailed only if
at least one of the logs has grown past its allowed size or if an
action has been taken. The mail option is very useful when chklogs
is run in an automated way such as via the cron daemon.

Using chklogs with CRON
----------------------
It is very useful to run chklogs automatically every now and then
such as every week or every month at a specified time, this way the
$admin user gets a reminder of what has been done or needs to be
done (-w option). Normally you can edit your crontab with the
`crontab -e' command. My crontab looks like this:

# DO NOT EDIT THIS FILE - edit the master and reinstall.
# (/tmp/crontab.1159 installed on Sun Mar  5 00:59:41 1995)
# (Cron version -- $Id: chklogs.txt,v 1.5 1995/12/20 20:45:06 root Rel $)
# crontab file for Root
00 21 * * sat       /home/root/bin/chklogs -m 

Thus running every saturday at 21:00 hours with the mail option.

Shuffling During Archival
-------------------------
Because archived logs will also occupy lots of space if not removed
when they have served their purpose it is necessary to limit the
amount of archived logs (per logfile). This is achieved by means of
the fourth column of the Log Index File therefore allowing you to
fine tune your maintenace by matching maximum allowed sizes with
maximum numbers of logs.

Shuffling is performed whenever an archive is made if and only if
the maximum number has been reached. During the shuffle operation the
oldest logfile is removed therefore assuring that your disk space is
not consumed by archives of logs. This mechanism is done with help
of the $f_max (read from Index File) and $maxlogs. $maxlogs is taken
as the default if the maximum given in the Index File is zero or
not specified.


Acknowledgements
----------------
* Thanks to Sam Lantinga <slouken@cs.ucdavis.edu> for the patch to
  improve configurability. Version 1.4
* Thanks to Michael Vergallen <mvergall@innet.be> for the patch to
  recreate archived log files. Version 1.5
* Thanks to Becca Thomas <beccat@magicats.org> for the shuffle
  suggestion for Ver. 1.6
* Thanks to David Ferrey <david@eos.uu.ch> for the suggestions to 
  improve archival, the explanation about POSIX & blocks and
  other ideas. Version 1.6
* Thanks to Andre Fachat <fachat@galileo.rhein-neckar.de> for the
  idea to tune the maximum number of logs and the multiple action  
  idea.
* Thanks to Niall Murphy for pointing out the syslogd/httpd
  control so that the logging is temporarily stopped. Version 1.6
* Also thanks to Zoltan Hidvegi <hzoli@cs.elte.hu>, Dustin Mollo
  <dustin@bugs.napanet.net>, and Samuli Karkkainen 
  <hskarkka@snakemail.hut.fi> for the suggestions, bug reports and 
  fixes of v1.7

My thanks also go to Bart Helberts and Kim Callis for their comments
and suggestions. If you use this script I would like to hear from you! 
any comments or suggestions are welcome :)

Sample Output File
------------------
			** c h k l o g s  V 1.7 **

System Logs Index: /etc/chklogs.conf    Sizes: bytes
Log Name                                           Current - Allowed  Action
-------------------------------------------------- -------   -------  ------
/var/spool/uucp/Log                                  37949     10000 truncated
/var/spool/cron/log                                  15077     10000 truncated
/var/spool/syslog/syslog                             50663     30000 archived
/var/spool/syslog/syslog.alert                           0       300    ok
/var/spool/syslog/syslog.err                             0     10000    ok
/var/spool/syslog/gn.log                             15980     30000    ok
/var/spool/syslog/ppp.log                                0     10000    ok
/var/adm/xferlog                                       954      8000    ok
/var/adm/smail/logfile                              124309     30000 archived
/var/adm/smail/paniclog                              44712      5000 archived
/home/majordom/majordomo/Log                          6422      7000    ok
/var/log/news/nntpsend.log                            6837     10000    ok
/usr/lib/news/log                                        0     10000    ok
/home/root/bin/junk/jjj                              24940       100 execute

Archives as <logname>.951219.gz


Save The Children!
------------------

Well, as you already know this program is totally free! However, would
it not be nice to make this world a better place by sending a small
contribution to your favourite charity? Mensen in Nood, Save The Children,
World Nature Funds etc.

Author
------
chklogs written by D. Emilio Grimaldo Tunon
EMAIL:  grimaldo@iaehv.iaehv.nl	    (Host machine)
	grimaldo@panama.iaehv.nl    (Linux PC @ home)
	grimaldo@sce.philips.nl	    (Work)
$Header: /home/root/bin/RCS/chklogs.txt,v 1.5 1995/12/20 20:45:06 root Rel $
