AWstats installation and setup

awstats: 7.7 (upstream)
Debian: stretch (9.11)
apache2: 2.4.25
perl: 5.24.1

1. Introduction

AWstats is a popular and powerfull Apache2 access-logfile analyser.

This document describes manual installation of “awstats”. Although there is a “awstats” Debian package, manual installation has the advantage of always using the latest upstream version and gives you more control over the installation process.

2. Installation

2.1 Prerequisites

  • perl >= 5.00503

2.2 Download "awstats" from upstream

Download the .tar.gz file or the .zip archive.

Extract the archive in “/usr/local”:

# cd /usr/local

# tar --no-same-owner -xzf _path_to_archive/awstats-7.7.tar.gz

# mv awstats-7.7 awstats


Do NOT run the configure script!
It doesn't handle the Debian apache2 configuration very well.

3. Configuration

3.1 Virtual hosting

Central to the configuration of awstats is the concept of virtual hosting. Each virtual host must have a distinct access logfile:


CustomLog ${APACHE_LOG_DIR}/access-vhostX.log combined
  • Note: The logformat must be set to “combined”.

3.2 Basic setup

For each virtual host create an awstats config file:

# mkdir /etc/awstats

# cd /etc/awstats

# cp /usr/local/awstats/wwwroot/cgi-bin/awstats.model.conf awstats.vhostX.conf

Edit the required parameters in “/etc/awstats/awstats.vhostX.conf”:








3.3 Building/updating statistics database

For each virtual host build the statistics database file.

Create the base directory to hold the awstats databases:

# mkdir /var/lib/awstats

Awstats comes with a tool to orderly process old log files: “logresolvemerge”. Awstats can read the resulting data via a pipe construct. 1)

Modify the awstat config file to read all access files:

# Use for first time setup.
# LogFile="/var/log/apache2/access-vhostX.log"
LogFile="/usr/local/awstats/tools/ /var/log/apache2/access-vhostX.log* |"
  • Note: Don't forget the “|” at the end of the LogFile line!

Create the database for vhostX:

# /usr/local/awstats/wwwroot/cgi-bin/ -config=vhostX -update

Create/Update database for config "/etc/awstats/awstats.vhostX.conf" by AWStats version 7.7 (build 20180105)
From data in log file "/var/log/apache2/access-vhostX.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: 58
 Found 0 dropped records,
 Found 0 comments,
 Found 0 blank records,
 Found 0 corrupted records,
 Found 0 old records,
 Found 58 new qualified records.

After successfully creating the database restore the awstat config file for normal operation:

# Use for first time setup.
# LogFile="/usr/local/awstats/tools/ /var/log/apache2/access-vhostX.log* |"

3.4 How to rotate my logs without losing data

(Awstats FAQ)

In order to prevent losing data we need to update the awstats data files before rotating the Apache2 access logfiles.

Create directory “httpd-prerotate”:

# cd /etc/logrotate.d

# mkdir httpd-prerotate

# cd httpd-prerotate/

Create prerotate script “awstats-update-all”:

test -x /usr/local/awstats/tools/ &&
  nice /usr/local/awstats/tools/ now >/dev/null

Make the new script executable:

# chmod +x 10-awstats.scr

3.5 Updating awstats databases using cron

Add a new crontab file “awstats” in /etc/cron.d/

# awstats crontab file

# min hour daymonth month dayweek user commandline
*/10 * * * * root test -x /usr/local/awstats/tools/ && nice /usr/local/awstats/tools/ now >/dev/null
  • Note: A cron definition can not expand over multiple lines!
  • Syntax “*/10” in the first field means every 10 minutes.

3.6 GeoIP Country database

(Awstats: Contribs, plugins and resources; More info: awstats vhost config file)

  • Note: Rebuild the awstats database file after configuring!

3.6.1 Perl Geo::IPfree

Install Perl Geo::IPfree

# apt-get install libgeo-ipfree-perl

Enable “geoipfree” plugin in awstats vhost config file(s):


3.6.2 Perl Geo::IP

Not tested.

3.7 Examine Querystrings (e.g. Dokuwiki)

  • Note: Rebuild the awstats database file after configuring!

By default awstats strips the querystring of the URLs. However this behaviour is inappropriate when examining a webservice which uses a querystring to identify each page. E.g. by default awstats will count all pages of a Dokuwiki as one page: /dokuwiki/doku.php

Enabling Querystring reading will solve this:


Limit the examination to these parameters (e.g. “id=”):


4. Reporting

Awstats has two reporting facilities:

  1. Dynamic reporting via Apache2/cgi
  2. Static HTML files using the commandline.

4.1 Dynamic reporting via Apache2/cgi

4.1.1 Enable mod_cgi (if not already enabled)

# cd /etc/apache2

# a2enmod cgi

4.1.2 Add cgi configuration

The awstats cgi configuration can be configured within each Apache2 virtual host configuration or in a general Apache2 section for all hosts.
In this How-to we configure awstats cgi in a general “conf-available” section.

# cd /etc/apache2/conf-available

Create a new file “serve-awstats.conf”:

<IfModule mod_alias.c>
    <IfModule mod_cgi.c>

    <IfModule mod_cgid.c>

        # Directives to allow use of AWStats as a CGI

        Alias /awstatsclasses "/usr/local/awstats/wwwroot/classes/"
        Alias /awstatscss "/usr/local/awstats/wwwroot/css/"
        Alias /awstatsicons "/usr/local/awstats/wwwroot/icon/"
        ScriptAlias /awstats/ "/usr/local/awstats/wwwroot/cgi-bin/"

        <Directory "/usr/local/awstats">
            AllowOverride None
            Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
            Require all granted

Enable the new configuration file:

# a2enconf serve-awstats

4.1.3 Activate all Apache2 modifications

Test the new Apache2 configuration:

# apache2ctl configtest

Syntax OK

Now restart Apache2:

# systemctl restart apache2

4.2 Static HTML files using the commandline

5. Troublesshooting

6. Documentation

6.1 Awstats website

6.2 report/update program

# /usr/local/awstats/wwwroot/cgi-bin/ -help

Copyright © 2020 - Author: Marjan Waldorp; 2020-02-29

logresolvemerge can read .gz/.bz2 files.
linux/applicaties/apache/awstats-install.txt · Laatst gewijzigd: 2020/03/01 14:26 (Externe bewerking)