====== 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 ====

  * https://www.awstats.org/#DOWNLOAD

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

Extract the archive in "/usr/local":

<code>
# cd /usr/local

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

# mv awstats-7.7 awstats
</code>
==== 2.3 awstats_configure.pl ====

Do NOT run the awstats_configure.pl 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:

/etc/apache2/sites-available/vhostX.conf:

<code>
CustomLog ${APACHE_LOG_DIR}/access-vhostX.log combined
</code>
  * Note: The logformat must be set to "combined".

==== 3.2 Basic setup ====

For each virtual host create an awstats config file:

<code>
# mkdir /etc/awstats

# cd /etc/awstats

# cp /usr/local/awstats/wwwroot/cgi-bin/awstats.model.conf awstats.vhostX.conf
</code>
Edit the required parameters in "/etc/awstats/awstats.vhostX.conf":

<code>
LogFile="/var/log/apache2/access-vhostX.log"

LogType=W

LogFormat=1

SiteDomain="www.somedom.com"

DirData="/var/lib/awstats"

DirCgi="/awstats"

DirIcons="/awstatsicons"
</code>
==== 3.3 Building/updating statistics database ====

For each virtual host build the statistics database file.

Create the base directory to hold the awstats databases:

<code>
# mkdir /var/lib/awstats
</code>
Awstats comes with a tool to orderly process old log files: "logresolvemerge". Awstats can read the resulting data via a pipe construct. ((logresolvemerge can read .gz/.bz2 files.
))

Modify the awstat config file to read all access files:

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

Create the database for vhostX:

<code>
# /usr/local/awstats/wwwroot/cgi-bin/awstats.pl -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.
</code>
After successfully creating the database restore the awstat config file for normal operation:

<code>
# Use logresolvemerge.pl for first time setup.
LogFile="/var/log/apache2/access-vhostX.log"
# LogFile="/usr/local/awstats/tools/logresolvemerge.pl /var/log/apache2/access-vhostX.log* |"
</code>
==== 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":

<code>
# cd /etc/logrotate.d

# mkdir httpd-prerotate

# cd httpd-prerotate/
</code>
Create prerotate script "awstats-update-all":

<code>
#!/bin/bash
test -x /usr/local/awstats/tools/awstats_updateall.pl &&
  nice /usr/local/awstats/tools/awstats_updateall.pl now >/dev/null
</code>
Make the new script executable:

<code>
# chmod +x 10-awstats.scr
</code>
==== 3.5 Updating awstats databases using cron ====

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

<code>
# awstats crontab file

# min hour daymonth month dayweek user commandline
*/10 * * * * root test -x /usr/local/awstats/tools/awstats_updateall.pl && nice /usr/local/awstats/tools/awstats_updateall.pl now >/dev/null
</code>
  * 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

<code>
# apt-get install libgeo-ipfree-perl
</code>
Enable "geoipfree" plugin in awstats vhost config file(s):

<code>
LoadPlugin="geoipfree"
</code>
=== 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:

<code>
URLWithQuery=1
</code>
Limit the examination to these parameters (e.g. "id="):

<code>
URLWithQueryWithOnlyFollowingParameters="id"
</code>
===== 4. Reporting =====

Awstats has two reporting facilities:

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

==== 4.1 Dynamic reporting via Apache2/cgi ====

=== 4.1.1 Enable mod_cgi (if not already enabled) ===

<code>
# cd /etc/apache2

# a2enmod cgi
</code>
=== 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.

<code>
# cd /etc/apache2/conf-available
</code>
Create a new file "serve-awstats.conf":

<code>
<IfModule mod_alias.c>
    <IfModule mod_cgi.c>
        Define ENABLE_USR_LIB_CGI_BIN
    </IfModule>

    <IfModule mod_cgid.c>
        Define ENABLE_USR_LIB_CGI_BIN
    </IfModule>

    <IfDefine ENABLE_USR_LIB_CGI_BIN>
        # 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
        </Directory>
    </IfDefine>
</IfModule>
</code>
Enable the new configuration file:

<code>
# a2enconf serve-awstats
</code>
=== 4.1.3 Activate all Apache2 modifications ===

Test the new Apache2 configuration:

<code>
# apache2ctl configtest

Syntax OK
</code>
Now restart Apache2:

<code>
# systemctl restart apache2
</code>
==== 4.2 Static HTML files using the commandline ====

See documentation: https://www.awstats.org/docs/awstats_setup.html#READ

===== 5. Troublesshooting =====

===== 6. Documentation =====

==== 6.1 Awstats website ====

https://www.awstats.org

==== 6.2 awstats.pl report/update program ====

<code>
# /usr/local/awstats/wwwroot/cgi-bin/awstats.pl -help
</code>

----

Copyright (c) 2020 Tux4u.be - Author: Marjan Waldorp; awstats-install.md 2020-02-29