awstats for Debian
==================

Quick'n'dirty setup
-------------------

Do the following for a simple setup of a single website with Apache 1.3.x:

  * Edit /etc/logrotate.d/apache to permit www-data access to logfiles
  * copy /usr/share/doc/awstats/examples/apache.conf to /etc/apache/conf.d/

The above is _NOT_ supported or recommended! Please read the rest of this
document instead...


No stats are generated
----------------------

As AWStats is used both as a CGI-script and offline, it is by default run as
uid=www-data in cron jobs so that generated files are accessible from CGI as
well.
By default Apache stores (since version 1.3.22-1) logfiles with uid=root and
gid=adm, so you need to either...

 1) Change the rights of the logfiles in /etc/logrotate.d/apache so that
    www-data has at least read access.

 2) As 1) but change to a specific user, and use the suEXEC feature of Apache
    to run as same user (and either change the right of /var/lib/awstats as
    well or use another directory). This is more complicated, but then the logs
    are not generally accessible to the server (which was probably the point of
    the Apache default).

 3) Change awstats.pl to group adm (but beware that you are then taking the
    risk of allowing a CGI-script access to admin stuff on the machine!).

With other webservers than Apache several things should probably be changed,
like location and format of logfiles.


A few minutes is lost each day/week/month
-----------------------------------------

By default AWStats scans logfiles each 10 minutes. When Apache (and other
webservers?) rotate their logfiles, the last entries in the old logfile may not
have been read by AWStats.

Make sure to run AWStats right _before_ web logs are rotated (add a "prerotate"
in /etc/logrotate.d/apache for Apache).


The icons are missing
---------------------

You should redirect requests for /awstats-icon/ to /usr/share/awstats/icon/.

In Apache, this is done by adding the following to /etc/apache/httpd.conf:

    Alias /awstats-icon/ /usr/share/awstats/icon/

For other webservers you should either do something similar, or make a symlink
from /var/www/awstats-icon to /usr/share/awstats/icon/.


Multiple stats
--------------

To handle multiple stats (eg. using VirtualHosts in Apache) you should...

 1) Place all configs in /etc/awstats.

 2) Name the configs "awstats." + whatever you want - ".conf" (eg.
    awstats.www.debian.org.conf"). But avoid "awstats.awstats.conf.

 3) Run awstats.pl with each config one by one (have a look at the scripts
    awstats-update and awstats_updateall.pl in
    /usr/share/doc/awstats/examples).


Browser and referer stats are missing
-------------------------------------

Apache uses CLF (Common Log Format) by default, which doesn't include info
about browser types and referer.

It is recommended to use "combined" logfiles instead (remember to change
awstats.conf accordingly).


Where is configure.pl?
----------------------

The main script may tell you to use /usr/lib/cgi-bin/tools/configure.pl.
That script, however, is not available as a CGI script on Debian.
Instead, it is located at /usr/share/doc/awstats/examples/awstats_configure.pl.


 -- Jonas Smedegaard <dr@jones.dk>  Fri,  8 Oct 2004 12:28:31 +0200