I was looking for a good traffic analyzer for my website when I came across AWStats. It looked good compared to other log analyzers, so I decided to give it a try. I’m a fan of the Debian operating system, which I use on most of my servers. So, like any typical Debian user, I used the package management system (APT) to install AWStats. Normally the Debian packages are pretty good for doing everything automatically for you, but not so with the AWStats package - which required some setting up. For those wanting to go this route, this is how you get AWStats’ Debian package to work with Apache.

Install AWStats

Start off by installing the AWStats package using APT.

apt-get install awstats

After installation, everything you need for AWStats can be found in the following directories:

/etc/awstats/

Configuration files for AWStats.

/usr/share/awstats/

Runtime libraries, plugins, language files, and icons.

/usr/share/doc/awstats/

README on how to setup AWStats. Consult if you are having problems.

/usr/share/doc/awstats/examples/

Setup and configuration scripts. If your looking for a script mentioned in the official docs, chances are it is here.

/usr/lib/cgi-bin/

Contains awstats.pl, the program itself.

Setup Apache

First thing that needs to be done is to setup Apache’s logging appropriately. I use Apache 2 on my server, so this article will be focused towards it.

Ensure that Apache is in fact logging access requests. For each virtual host (found in /etc/apache2/sites-enabled/), make sure there is something like the following present: (replace example.com with the virtual host domain name)

CustomLog /var/log/apache2/access.example.com.log combined

You can also check the main configuration file (/etc/apache2/apache2.conf) to see if a global CustomLog is specified, however, it is recommended that you create a log for each individual domain name. In any case, make sure that the last parameter of CustomLog is combined as it will help AWStats produce better results. (Note: that if you already have a CustomLog directive in your configuration file that uses something else other then combined, please delete the already pre-existing log files.)

Before we are done, copy /usr/share/doc/awstats/examples/apache.conf to /etc/apache2/conf.d/awstats.conf. This will setup the necessary aliases to access AWStats from the web (on all virtual hosts). If you would like to control which virtual hosts will have these aliases specified, then copy the code within apache.conf into a virtual host definition:

# This provides worldwide access to everything below the directory
<directory /var/lib/awstats>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
</directory>
 
# This provides worldwide access to everything below the directory
<directory /usr/share/awstats/icon>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
</directory>
 
# This provides worldwide access to everything in the directory
Alias /awstats-icon/ /usr/share/awstats/icon/
 
# This (hopefully) enables _all_ CGI scripts in the default directory
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

Don’t forget to restart Apache when your done:

/etc/init.d/apache2 restart

Setup AWStats

Next step is to setup the AWStats configuration files. In /etc/awstats/, you will see the file awstats.conf. It is recommended that you setup a configuration file for each virtual host that you want to monitor. To do this, copy awstats.conf to awstats.example.com.conf. (Replacing example.com with your domain name.) Next, go through awstats.example.com.conf and customize it for your site. The critical options to change are:

#Log file for virtual domain
LogFile="/var/log/apache2/access.example.com.log"
 
#Log type: Web
LogType=W
 
#Apache or Lotus Notes/Domino native combined log format (NCSA combined/XLF/ELF log format)
LogFormat=1
 
#Main domain name used to reach website. Used for log parsing (skipping) and server-side link generation.
SiteDomain="example.com"
 
#Other domain names that can be used to access web site. This example uses a regular expression to reduce typing.
HostAliases="REGEX[(www\.)?example\.(com|net|org)$]"

Testing

We can now generate statistics for your website by running AWStats:

/usr/lib/cgi-bin/awstats.pl -config=example.com -update

Which should output something like:

Update for config "/etc/awstats/awstats.example.com.conf"
With data in log file "/var/log/apache2/access.example.com.log"...
Phase 1 : First bypass old records, searching new record...
Parsed lines in file: 5
 Found 0 dropped records,
 Found 0 corrupted records,
 Found 0 old records,
 Found 5 new qualified records.

Providing there are no errors, we can view the results by pointing our web browser to:

http://example.com/cgi-bin/awstats.pl?config=example.com

Automation

At the moment, statistics will only be generated when you run the script manually. Therefore, lets automate it as a cron job. In /etc/cron.d/ there will already be a file called awstats. Theoretically you should be able to edit this file and change the part -config=, but I couldn’t get this to work. So, I wrote my own which I find works for me. If you’d like to do the same, replace the content of awstats with:

0 * * * * www-data /usr/lib/cgi-bin/awstats.pl -config=example.com -update >/dev/null

This code will cause your statistics to be generated every hour.

Now, there’s one small problem with this. For anyone familiar with Apache, you know that, by default, the Apache logs are rotated (to prevent them from getting to big) . This causes a problem that if entries to the logs are made between awstats running and the logs rotated, those entries are lost. Therefore, we need to modify /etc/logrotate.d/apache2, and add some prerotate code:

/var/log/apache2/*.log {
        weekly
        missingok
        rotate 52
        compress
        delaycompress
        notifempty
        create 644 root adm
        sharedscripts
        prerotate
                /usr/lib/cgi-bin/awstats.pl -config=example.com -update
        endscript
        postrotate
                if [ -f /var/run/apache2.pid ]; then
                        /etc/init.d/apache2 restart > /dev/null
                fi
        endscript
}

The changes I have made are:

• Added the prerotate section:

  prerotate
          /usr/lib/cgi-bin/awstats.pl -config=example.com -update
  endscript
  

• Changed the permissions on the log files:

  create 644 root adm
  

Note that the permission change is to allow the cron job (running as user www-data) to access the log files. (This is the lazy way) If you already have pre-existing log files, you can change their permission by running:

chmod o+r /var/log/apache2/*.log

If you don’t want to allow all users read access to the log files, then you can try changing the group owner on the log files to www-data. (I haven’t tried this, so no guarantee it will work)

Conclusion

There we have it, getting AWStats to run on Debian. One of the things I would recommend, before leaving this, is to secure the the generated results with a username and password (using Apache’s mod_auth). Although it is out of the scope of this article, if you would like me to go about showing you, please mention in the comments.

For more information on AWStats configuration options and abilities, please see their official documentation.