------------------------------------------------------------------------
amavis-stats - generate e-mail statistics from logfiles
------------------------------------------------------------------------

This software requires RRDTool software, PHP with GD support.

It appears to work best with RRDTool-1.0.49 due to font issues however, I
have heard reports that suitable font replacements can be found for version
1.2.x.

Don't forget to add an 'include' statement for the amavis-stats.alias.conf
to your httpd.conf file if you haven't done so already.

Licence
-------
Copyright (C) 2005, Dale Walsh (buildsmart@daleenterprise.com)

Dependencies
------------
As of version 0.1.14 amavis-stats works with amavisd-new on Mac OSX, linux,
RH and Solaris and a host of other Unix environments.

SEE CHANGELOG

The Following content is from the original Author and is left intact and
provided as is, you can use it as a rough guide to help determine how to
configure the new version for installation without loosing any data but you
should rely on the output of './configure --help' for available configuration
options because things have changed considerably.


Licence
-------
Copyright (C) 2003, Mark Lawrence (nomad@null.net)

amavis-stats is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.


Author (original)
------
Mark Lawrence <nomad@null.net>. Aussie living in Switzerland.
Comments are welcome. So would somewhere else to host this.


Author (current)
------
Dale Walsh (buildsmart@daleenterprise.com). Canadian living in USA.
Comments are welcome.


Description
-----------
amavis-stats is a simple amavis statistics generator based on rrdtool. It
produces graphs of clean emails, spam emails and infected emails broken
down by virus, from amavis log entries (such as /var/log/mail.info).

You can see an example of this in action here:

  http://rekudos.net/amavis-stats/

The RRD files are created and updated by a perl script. Since the script
uses the date/time values from the log entries it can be run (ir)regularly
from cron(8) or by hand as desired. Graphs are generated by a php script.


Dependencies
------------
As of version 0.1.4 amavis-stats works with amavisd and amavisd-new on linux,
Solaris and Mac OSX.

The perl script uses nothing which probably isn't in the standard perl
installation plus the RRDTool installation.

Graphs are generated by php in combination with either the command-line
rrdtool or the PHP-rrdtool module.


Download
--------
Raw Source:
    http://amavis-stats.com/download/amavis-stats-X.X.X.tar.gz


Install (not debian or rpm)
-------
1. Download and extract the source:

 root# wget http://amavis-stats.com/download/amavis-stats-X.X.X.tar.gz
 or
 root# curl -OL http://amavis-stats.com/download/amavis-stats-X.X.X.tar.gz

 root# tar -xvf amavis-stats-X.X.X.tar.gz
 root# cd amavis-stats-X.X.X/

2. Install the program by typing (as root):

 root# ./configure [options]
 root# make
 root# make install

The options to configure (apart from the standards) can be:

  --with-user=USER            specify user which webserver runs as [defaults to 'www']
  --with-group=GROUP          specify group which webserver runs as [defaults to 'www']
  --with-setrgid	          if your perl supports setrgid [defaults to 'no']
  --with-rrdtool[=DIR]	      location of rrdtool [defaults to '/usr/local/rrdtool']
  --with-php-config=PATH	  path to php-config [searches '$PATH' if not specified]
  --enable-id-check           use id utility instead of /etc/passwd parsing
  --enable-yp-check           use ypmatch utility instead of /etc/passwd parsing
  --enable-netinfo-check      use netinfo utility instead of /etc/passwd parsing
  --disable-startup           disable startup item
  --disable-web               disable test for web user/group

The web-user,group must already exist - they will *not* be automatically created.

4. If you should already have a user for apache, You should also check that
the user has permissions to read your particular log file. 
Otherwise you can run it as root, but no responsibility lies here for that.

You should then see a bunch of rrd files in /var/lib/amavis-stats.

5. If all has gone well you should be able to hit
http://localhost/amavis-stats/ with your web-browser and see some nice
looking graphs.

6. Most systems implement some sort of logrotate(8) function, to rotate
log files and optionally compress them. Because amavis-stats cannot unzip
files you should add a "delaycompress" option to your /etc/logrotate.conf
or the appropriate /etc/logrotate.d/* file.

7. I suggest that you send mail for the "amavis" user to another account on
the system as amavis-stats generates text each time it sees a new virus
or has some error.

I am also thinking of possibly generating further statistical information
for a days worth of events. Such things as:

- Top 10 recipients of SPAM, BANNED, INFECTED, Passed emails
- Top 10 senders of SPAM, BANNED, INFECTED, Passed emails

If you would find this useful please let me know.


Problems/FAQ
------------
Q. What is the best way to handle rotated (*.gz) logfiles? How do I
get all of the history in the graphs and not just the latest log?

A. amavis-stats doesn't handle .tar or .gz files at the moment. What it
expects is just the name of a single uncompressed file. So when I first
install it on a machine I usually do the following to get the history:

amavis$ ls mail.info*
mail.info  mail.info.0  mail.info.1.gz  mail.info.2.gz  mail.info.3.gz

amavis$ sudo gzip -d mail.info.*.gz
amavis$ /usr/sbin/amavis-stats -r mail.info.3
amavis$ /usr/sbin/amavis-stats -r mail.info.2
amavis$ /usr/sbin/amavis-stats -r mail.info.1
amavis$ /usr/sbin/amavis-stats -r mail.info.0
amavis$ /usr/sbin/amavis-stats -r mail.info
amavis$ sudo gzip mail.info.[1-3]

ie, you have to manually run ammavis-stats (as your "amavis" user) on each
file in the correct chronological order

Also see the comment above about "delaycompress" in your log rotation
configuration.

Q. We restarted the amavisd with another loglevel (the default one: 0) and
now I dont get any spam info in the amavis-stats. Where did it go?

A. Spam information is only generated in some versions of amavis when the
log level is set to a higher value. There is an effort underway to
standardise the log output of all the Amavis, but please be patient, this
will take some time.


Q. The rrd files seem to get generated ok but I when I try and display the
web page I get the error: amavis-stats::error: rrd_graph(): 127

A. I believe that the error code 127 is returned from bash when it can't find
the program to execute. I guess in this case that your web user (www-data
or www or web) is unable to find the "rrdtool" executable. Perhaps it is
not in the standard location, or the path for that user is not set?

You could try the following to see if the tool can be found.

    root# su -c env - www | grep PATH
        root# su -c rrdtool - www


