##### Overview

The amavis-logwatch utility produces summaries and statistics
regarding the operation of amavis. This utility can be used as
a standalone program, or as a logwatch filter module to produce
amavis summary and detailed reports within logwatch.

A key feature of this utility is the ability to produce brief
summary reports for a quick overview of general amavis operations,
or to produce highly detailed reports, hierarchically-arranged for
further insight into malware sources and other email issues. 

Much of the interesting data is available when amavisd-new's
$log_level is set to at least 2.  See "Amavis log level" below.

##### Installation: standalone

The included Makefile will install the amavis-logwatch utility
for you.  Run:

    make install-standalone

to install the utility and its configuration file.  Installation
will default to /usr/local/bin and /usr/local/etc, respectively.
 
##### Installation: logwatch

To use amavis-logwatch as a logwatch script, the files:
 
    amavis-logwatch
    amavis-logwatch.conf
 
will need to be installed into one of logwatch's known directories.
To avoid overwriting your existing default logwatch filter files,
the enclosed files can be installed into the global logwatch
installation directory, which is typically:

   /etc/logwatch

The included Makefile can be used to install the files into
/etc/logwatch for you. To install the filter into an existing
logwatch installation, run:

    make install-logwatch

NOTE: the files amavis-logwatch and amavis-logwatch.conf must be
renamed (by removing the "-logwatch" suffix), for logwatch to
function correctly.  The Makefile takes care of this.

For non-standard installations, you will need to determine your
global logwatch directory, and define "prefix" in the attached
Makefile.

Alternatively, you can manually copy the files to their proper
locations:

    cp amavis-logwatch       /etc/logwatch/scripts/services/amavis
    cp amavis-logwatch.conf  /etc/logwatch/conf/services/amavis.conf

##### Amavis Log Level

Amavis provides additional log information when the variable 
$log_level is increased above the default 0 value.  This information
is used by the amavis-logwatch filter to provide additional reports,
not available with the default $log_level=0 value.  A log_level of
2 is suggested.

If you prefer not to increase the noise level in your main mail
or amavis logs, you can configure syslog to log amavis' output
to multiple log files, where basic log entries are routed to
your main mail log(s) and more detailed entries routed to an
amavis-specific log file used to feed the amavis-logwatch utility.

A convenient way to accomplish this is to change the amavis
configuration variables in amavisd.conf as shown below:

amavisd.conf:
    $log_level = 2;
    $syslog_facility = 'local5';
    $syslog_priority = 'debug';

This increases the log level to 2, and sends amavis' log entries to
an alternate syslog facility (eg. local5, user), which can then be
routed to one or more log files, including your main mail log file:

syslog.conf:
    #
    #mail.info                         -/var/log/maillog
    mail.info;local5.notice            -/var/log/maillog

    local5.info                        -/var/log/amavisd-info.log

Amavis' typical log_level 0 messages will go to both your maillog
and to the amavisd-info.log file, but higher log_level messages
will only be routed to the amavisd-info.log file.  Search the
amavisd-new RELEASE_NOTES for:

    "syslog priorities are now dynamically derived"

for additional information on amavisd-new's logging.

##### Usage

The amavis-logwatch utility is used standalone as:

   amavis-logwatch ...

and within logwatch as:

   logwatch --service amavis ...

See examples below for more usage scenarios.


# Standalone or as a logwatch filter

The configuration file amavis-logwatch.conf contains variables that
control runtime aspects of amavis-logwatch.  This configuration
file is required when running amavis-logwatch as a logwatch filter,
but is optional in standalone mode.  When running standalone, command
line options always override configuration file settings.

Variables in the configuration file used to control amavis-logwatch
are prefixed with "$amavis_" (this is a logwatch requirement; all
other non-prefixed variables within the file are used by logwatch
itself). 

When running in standalone mode, command-line options do not use
the "amavis_" prefix, but match their corresponding counterparts
within the configuration file.

The --detail option controls the global volume of output, when
running amavis-logwatch either within logwatch or as a standalone 
utility.

At --detail 4 or less, amavis-logwatch will produce only a Summary
section of amavis activity.  At --detail 5 and above, a Details
section is also produced.  Each incremental increase in --detail
level generates one additional hierarchical sub-level of output
in the Details section of the report.  Although level 10 provides all
levels of (possibly cropped) output, --detail 11 will prevent
output line cropping for full disclosure.

While --detail controls the maximum number of levels of output
globally, each level in the Detailed section may be maximized
independently.  This allows "noise" reduction for easier log
reading, while still providing additional levels of detail where
interesting.  Furthermore, a Top N feature is available per
section as well.

Read the comments in the amavis-logwatch.conf file for additional
information.

##### Examples: Standalone

To run amavis-logwatch in standalone mode, simply run

   amavis-logwatch /path/to/amavisd-new.log

A complete list of options is available via:

   amavis-logwatch --help

To print a summary report of amavis log data:

   amavis-logwatch --detail 1 /path/to/amavisd-new.log

Currently, when running amavis-logwatch in standalone mode, there
is no internal support for producing reports for a given period
of time; this can be accomplished with a simple grep:

   grep 'May 25' /var/log/maillog | amavis-logwatch --detail 6

##### Examples: Logwatch
 
To print a summary report for today's amavis log data:

    logwatch --print --service amavis --range today --detail 1

To print a report for today's amavis log data, with one level
of detail in the Details section:

    logwatch --print --service amavis --range today --detail 5

To print a report for yesterday's amavis log data, with two level
of detail in the Details section:

    logwatch --print --service amavis --range yesterday --detail 6

To print a report from Dec 12th thru Dec 14th, with four levels
of detail in the Details section:

    logwatch --print --service amavis --range \
    	'between 12/12 and 12/14' --detail 8

To print a report for today, with all levels of detail:

    logwatch --print --service amavis --range today --detail 10

Same as above, but leaves long lines uncropped:

    logwatch --print --service amavis --range today --detail 11

Mike Cappella
07/03/2007
lists-logwatch (at) cappella.us
