Installing awstats on Ubuntu HOWTO

This page will guide you through the process of installing awstats 6.5 on Ubuntu Dapper.

Installing awstats is a fairly pain-free process, but its default settings might not be inherently secure. You might not want to take throw these meticulously detailed website statistics out to the public, especially not for production sites.
This HOWTO will therefore attempt to leave you with a secure awstats installation.

Verify CGI is installed and enabled

We'll assume you already have apache2 running. Tell aptitude to install the latest awstats package:

Shell command:
$ sudo aptitude install awstats
Tells aptitude to install package awstats

Next, you'll need to have CGI installed and enabled on your server. It comes standard with the Ubuntu apache2 package, but make sure it's loaded when Apache starts:

Shell command:
$ ls -la /etc/apache2/mods-enabled/
Look up a list of enabled modules for apache2

It should note a symbolic link (cyan-colored) linked to /etc/apache2/mods-available/cgi.load.

Now check your virtual host configuration file whether the cgi-bin directory is routed correctly. Your actual virtual host file might be different than the one stated here:

Shell command:
$ sudo vim /etc/apache2/sites-enabled/000-default
Edit default virtual host file

Look for the section ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/.

Unless you want your awstats open to the public, you might want to add some access rules so that your awstats aren't available to everybody. Putting them in the virtual host config does require apache2 to be restarted, but saves you the trouble of editing redundant .htaccess files. And after initial configuration, chances are slim you'll have to review this part of the file again.

These are my recommended security settings:

/etc/apache2/sites-enabled/000-default
# Tell Apache where to find URLs that look like:
# http://dw.ig3.net/cgi-bin

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

# Enable icon support for awstats.

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

# Disallow .htaccess files

AllowOverride None

Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch

# Security measures to prevent unauthorized access

Order Allow,Deny

Allow from public_ip

Allow from 172.16.0.*

# Disallow .htaccess files

AllowOverride None

Options None

# Security measures to prevent unauthorized access

Order Allow,Deny

Allow from public_ip

Allow from 172.16.0.*

The Allow from directives specify which hosts and/or IP ranges are allowed to access your awstats. If you include both your public IP and your LAN's address range, everybody on your local network (or connected through a VPN or SSH SOCKS proxy) can see your stats. Replace public_ip and 172.16.0.* with your own public IP and LAN address range.

The line Alias /awstats-icon/ /usr/share/awstats/icon/ allows awstats to use its icons. Although not mandatory, it does look a lot prettier with.

Restart apache2 for the changes to take effect:

Shell command: 
$ sudo /etc/init.d/apache2 restart
Tell apache2 to re-read its configuration file and restart

Configuring awstats

With that secured, let's move on to configuring awstats. We'll only describe here how to configure awstats for a single host.

Shell command: 
$ sudo vim /etc/awstats/awstats.conf
Edit the awstats configuration file

Scroll down to the line

LogFile="/var/log/apache/access.log"

and replace that with

LogFile="/var/log/apache2/access.log"

Go to

SiteDomain=""

and fill in your own site's domain.

That should cover the required setup. There are many other well-documented optional features that you can set, but I'll leave those to you.

awstats needs to be updated periodically. During an update, it will scan through your apache2 log files and create a statistics page based on that.
The Ubuntu awstats package automatically creates a cron job for you that will take for these periodic updates. Let's see what they got us:

Shell command: 
$ sudo vim /etc/cron.d/awstats
Edit the awstats cron job file

/etc/cron.d/awstats
0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a

-f /etc/awstats/awstats.conf -a

-r /var/log/apache/access.log ] && /usr/lib/cgi-bin/awstats.pl

-config=awstats -update >/dev/null

0,10,20,30,40,50 Tells the cron daemon to execute this line every 10 minutes.

www-data Specifies the user that will run this program. www-data is the same user that also runs the apache2 program in the background.

-f /etc/awstats/awstats.conf Tells the awstats.pl program where to find its config file.

-r /var/log/apache/access.log Tells the awstats.pl program where to find the Apache log files.

Almost correct, but our access.log file is located in /var/log/apache2, and not in /var/log/apache. Update the line:

/etc/cron.d/awstats
0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a

-f /etc/awstats/awstats.conf -a

-r /var/log/apache2/access.log ] && /usr/lib/cgi-bin/awstats.pl

-config=awstats -update >/dev/null

-config=awstats -update >/dev/null Tells awstats to use the config file awstats.conf, (located in /etc/awstats) to update its data, and to not send the results as an email.

Let's update our awstats for the first time. The cron daemon will take care that every 10 minutes, this command will be run:

Shell command: 
$ sudo /usr/lib/cgi-bin/awstats.pl -config=awstats -update
Update awstats data for configuration file /etc/awstats.conf

This might take a while. You output should look like this:

Output: 
Update for config "/etc/awstats/awstats.conf"

With data in log file "/var/log/apache2/access.log"...

Phase 1 : First bypass old records, searching new record...

Searching new records from beginning of log file...

Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...

Jumped lines in file: 0

Parsed lines in file: 23

Found 0 dropped records,

Found 0 corrupted records,

Found 0 old records,

Found 23 new qualified records.

Now go and check out your stats! They're located at /cgi-bin/awstats.pl.