$Id: README,v 1.5 2002/03/04 21:03:13 tellini Exp $

mod_accounting                http://mod-acct.sourceforge.net 


What is it?
===========

mod_accounting is a simple Apache module that can record 
traffic statistics into a database (bytes in/out per http 
request)


Who did it?
===========

Simone Tellini, <tellini@users.sourceforge.net>

If you use this software in a production environment and/or
you wish to show your support, you can get me something off
my Amazon wish-list, located at 
http://www.amazon.co.uk/exec/obidos/wishlist/1K4OWZ581SIRE/

In any case, have fun with it :)


Installation
============

Edit the Makefile to check these things:

 - at least apxs is in the path, otherwise specify where to 
   find it

 - decide which DB driver you want to be included in the
   module and remove the NEED_xx definitions you don't like

 - make sure the libraries path is correct

Then "make install" should compile and install the module into
the correct apache directory.


Configuration
=============

The module adds these configuration directives:

 AccountingQueryFmt: the query to execute to log the transactions. 
                     Available placeholders are %s for sent bytes, 
                     %r for received ones, %h for the virtual host
                     name, %u for the user name.

 AccountingDatabase: the name of the database for logging.

 AccountingDatabaseDriver: the name of the database driver.

 AccountingDBHost: host and port needed to connect to the database

 AccountingLoginInfo: user and password required for logging into 
                      the database

 AccountingTimedUpdates: number of seconds to wait between 2 update queries 
                         (performance tuning)

 AccountingIgnoreHosts: a list of hosts to ignore. You can specify a
                        single IP (e.g. 192.168.1.1), a host/mask pair
                        (e.g. 192.168.1.1/255.255.255.0) or a range
                        (e.g. 192.168.1.1-192.168.1.5)

An example:

    AccountingQueryFmt "UPDATE ipaccounting SET bytesin = bytesin + %r, bytesout = bytesout + %s WHERE LOWER( host ) = LOWER( '%h' )"
    AccountingDatabase accounting
    AccountingDatabaseDriver postgres
    AccountingDBHost localhost 5432
    AccountingLoginInfo acct acct


Currently it supports postgres or mysql as DB drivers.

NOTE: 
the %u placeholder can NOT be used together with AccountintTimedUpdates


Query examples
==============

On Tue, 19 Feb 2002 00:43:07 -0300 Carlos Kumbak wrote:

CK>     -Traffic accounting per virtual host
CK>     -Traffic accounting per user
CK>     -Traffic accounting per user x virtual host
CK>     -Traffic accounting period (date/time/user/virtual host/user x virtual host)

It seems to me that the only thing lacking is a placeholder for the user
name to be used in queries. If I add that you could use a query like:

INSERT INTO ipacct( tstamp, vhost, user, bytesin, bytesout ) 
VALUES( NOW() , '%h', '%u', %r, %s );

Then you would be able to do all of the above mentioned statistics with
different SELECT queries.

Of course your table should have a datetime column 'tstamp' and a varchar 'user'
one.
