How To Setup AWStats For A Domain In Debian Jessie

AWStats is a fantastic server-side program that can keep track of every single hit or view that your website gets. It can give you a lot more detailed information than say Google Analytics or WordPress statistics plugins, because it directly accesses the server logs, while Google Analytics and WordPress only log those specific pages where their front-end code is placed in your website.

This article will give you step-by-step instructions on how to install, and setup AWStats so that you have a great way to check how much traffic your site gets every day.

A Few Assumptions In This Article

This article assumes that awstats is not already installed on yours system. In addition, it assumes that you are connecting to VPS or on your own computer, that you have already setup DNS and Apache for your domain, and that your domain name is example.com (substitute example.com for whatever your domain name is).

A quick note to avoid confusion: In this article I refer both to AWStats and awstats. When talking about the program, it is spelled AWStats, but the software we are going to install and configure is spelled awstats. It is important when dealing with the software, to only use awstats because case matters. This article will mainly just write awstats.

Step 1: Update And Upgrade Debian

In to make sure you are using the most up-to-date software, you need to first do the following.

sudo apt-get update && sudo apt-get upgrade -y

Step 2: Install awstats

Installing awstats is simple. Simply type:

sudo apt-get install awstats

Step 3: Change Into The awstats Directory And Copy The Default Config File

After awstats is installed type:

cd /etc/awstats

Once you are in the awstats directory, you should be able to see,
after doing an ls  command that you have a file called:
awstats.conf

awstats.conf is the file you will need to copy for your domain, so that you can have a domain-specific config file. You need to copy the awstats file for your domain.

sudo cp awstats.conf awstats.example.com.conf

substitute example.com with whatever your domain is called.

Step 4: Add SiteDomain Information

Next, you need to edit the file awstats.example.com.conf to add an important line for awstats to know which domain you are getting data from.

You are going to add the following line SiteDomain="example.com". There might already be a line in the file, like SiteDomain=”” commented out with #. If one exists, you can either remove the comment, or just add a whole new line with SiteDomain="example.com"

Now, edit awstats.example.com.conf and add that line
sudo vim awstats.example.com.conf

Now add the following line to the file
SiteDomain="example.com"

And now save and exit the file.

Step 5: Find Out Where Your Apache Logs Are Stored. Then edit awstats config file.

In order to have awstats work properly, it has to know exactly what your Apache log files for your domain are called, and exactly where they are located. Type:

cd /etc/apache2/sites-available

Next, find your domain’s apache config file and open it with a text editor. I am using vim, but you can use whichever text editor you like.

sudo vim example.com.conf

I assume you have a custom log. Look for the word CustomLog. For example, in my file, it looks like

CustomLog ${APACHE_LOG_DIR}/example.com.log combined

It may be different for you, the key is just to find out where your files are logged. So, from the above CustomLog line, I learn that my computer stores my domain’s Apache log files at
/var/log/apache2/example.com.log

Now, make a note of that. Next, once you know where the log files are stored, you are going to have to edit the awstats config file.

cd /etc/awstats/

now add a line called LogFile to that file. You will be adding the exact location of your log file location.

The following is what example.com would look like if my log files were located at /var/log/apache2/example.com.log.

Add the following line to the file awstats.example.com.conf

LogFile="/var/log/apache2/example.com.log"

Step 6: Generate The Initial Stats For awstats For Your Site

Type the following command (remember to substitute in your actual domain name):

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

After you enter in that command, it may take several seconds, or even several minutes, depending on how many entries you have in your Apache log files. For example, if you have thousands of entries, it may take a while.

After it is done, if it is successful, with no errors, you should get some output like:

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

Step 7: Enable mod_cgi in Apache

If you haven’t already done so, you need to enable a mod in Apache called cgi. cgi stands for common gateway interface, and it is one software that allows you to run code for various programming languages on a server. AWStats is written in Perl, so we need to use cgi to run Perl on the server.

Type the command:

sudo a2enmod cgi

Next you should see output like:

Enabling module cgi.
To activate the new configuration, you need to run:
  service apache2 restart

You need to restart Apache, so type:

sudo service apache2 restart

Step 8: Configure Apache To Work With awstats

Now, we will edit our Apache config file, and add some essential code for awstats to work with Apache.

cd /etc/apache2/sites-available/

Before you do any more configuring, I recommend you backup your apache2 config file, so that you if make a mistake, you can always recover your original Apache file and start over.

Here, I will copy the config file to the ~/ directory

cp example.com.conf  ~/example.com.conf.original

Once you have backed up your Apache config file, we can continue. (Note if you use HTTPS on your site, make sure to back up the other Apache config file as well, such as example.com-le-ssl.conf)

Now, we will edit our Apache file again.

sudo vim example.com.conf

Below is the default code (you can edit it later) that you need to paste into your config file. I recommend you put it at the bottom of the file (above the </VirtualHost> line, but it is fine to put it anywhere inside the file.)

Alias /awstatsclasses "/usr/share/awstats/lib/"
Alias /awstats-icon "/usr/share/awstats/icon/"
Alias /awstatscss "/usr/share/doc/awstats/examples/css"
ScriptAlias /awstats/ /usr/lib/cgi-bin/
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch

After you have pasted in that code, save the file.

Next, if you use HTTPS on your site, you need to edit the HTTPS config file as well (if you don’t use HTTPS, you can skip this step)

Paste in the same code as above, but into the HTTPS file

sudo vim example.com-le-ssl.conf

And again paste in this code anywhere in the HTTPS config file.

Alias /awstatsclasses "/usr/share/awstats/lib/"
Alias /awstats-icon "/usr/share/awstats/icon/"
Alias /awstatscss "/usr/share/doc/awstats/examples/css"
ScriptAlias /awstats/ /usr/lib/cgi-bin/
Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch

And save the file. Finally, restart Apache.

sudo service apache2 restart

If everything went well, awstats should now be up and running for your site. (If there is an error, you can go back through the previous steps and troubleshoot.)

To test if awstats was setup properly, open up a browser (remember to substitute in your own domain) and go to

example.com/awstats/awstats.pl

If you can see some an image like the following, you know that you setup awstats correctly.

Congratulations!!!!

Addtional Steps After AWStats Initially Setup

Now, we will do some tweaking. As of now, awstats will not automatically update. To update the stats manually, you will need to type:

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

But, you will likely find this tedious and a waste of time. You can have the computer automate this operation for you, and update awstats as often as you want.

Step 8: Setup A Cron Job To Automatically Update Your AWStats Frequently

A cron job is a way to have a computer automate work, over and over, based on a time schedule you set. Cron jobs are technically unnecessary for awstats, but they are incredibly useful, and will
save you lots of time.

Because updating awstats requires root permission, we will need to update the crontab file of the root user. Type:

sudo crontab -e

If you haven’t used crontab before, Debian will ask you which text editor you would like to use. You will get ouput like the following:

no crontab for root - using an empty one

Select an editor.  To change later, run 'select-editor'.
  1. /bin/nano        <---- easiest
  2. /usr/bin/vim.basic
  3. /usr/bin/vim.tiny

Choose 1-3 [1]: 

Personally, because vim is my favorite text editor, I chose and typed 2, but you can choose whichever you want. If you change your mind after your initial selection, you can always re-configure late which is the default text editor to use with crontab.

After selecting which text editor you will use, the default crontab file should look something like the following if you haven’t made cron jobs before.

# Edit this file to introduce tasks to be run by cron.
# 
# Each task to run has to be defined through a single line
# indicating with different fields when the task will be run
# and what command to run for the task
# 
# To define the time you can provide concrete values for
# minute (m), hour (h), day of month (dom), month (mon),
# and day of week (dow) or use '*' in these fields (for 'any').# 
# Notice that tasks will be started based on the cron's system
# daemon's notion of time and timezones.
# 
# Output of the crontab jobs (including errors) is sent through
# email to the user the crontab file belongs to (unless redirected).
# 
# For example, you can run a backup of all your user accounts
# at 5 a.m every week with:
# 0 5 * * 1 tar -zcf /var/backups/home.tgz /home/
# 
# For more information see the manual pages of crontab(5) and cron(8)
# 
# m h  dom mon dow   command

Now, you need to edit this file to create your cron job.
The cron job I use is something like:

0,10,20,30,40,50 * * * * sudo /usr/lib/cgi-bin/awstats.pl -config=example.com -update > /dev/null

So, at the bottom of your crontab file, add a new line and enter

0,10,20,30,40,50 * * * * sudo /usr/lib/cgi-bin/awstats.pl -config=yourdomain.com -update > /dev/null

Then save and exit the file. The command I gave you will update awstats every 10 minutes of every hour of every day.

After you have saved the file, close the file. If you would like to use a different cron job, you can research crontab on the Internet or read the man page for crontab.

Step 8: Better Security For AWStats

Unless you secure your awstats page, example.com/awstats/awstats.pl, it will be public, that is to say, anyone could access your awstats. If that doesn’t bother you, you can skip this step. No one would be able to change your stats, but you might not want others to be able to view them. You could password protect the file and/or use a different alias. I personally like using a different alias than awstats, one which is very difficult to guess, so I likely won’t have to bother with setting up a username and password with the htaccess file, or in the Apache file. Instead of having our awstats accessible by going to example.com/awstats/awstats.pl, let’s have it go to a different address. We need to edit our Apache config file again.

cd /etc/apache2/sites-available

Now edit the file

sudo vim example.com.conf

Comment out the following line: by adding a # before it

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

After commenting out the line, it the line should then look like

#ScriptAlias /awstats/ /usr/lib/cgi-bin/

Think of what alias you would like; it can be anything. The example I will use as a different alias is, bookchairheadphones. I think it is highly unlikely someone would be able to guess that, so initially it is safe.
So, to make the new alias bookchairheadphones, paste the following line below the line that you commented out.

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

And then save and exit the file. If you use HTTPS on your site, do the same for your HTTPS file

sudo vim example.com-le-ssl.conf

Comment out the following line: by adding a # before it

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

It should then look like

#ScriptAlias /awstats/ /usr/lib/cgi-bin/

Paste the following line below the line that you commented out.

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

And then save and exit the file.

Finally, we need to restart apache one last time

sudo service apache2 restart

Now, try going to:

example.com/bookchairheadphones/awstats.pl
remember to substitute in your real domain, and also remember that you can choose any alias you want. You should now have your awstats always accesible at example.com/bookchairheadphones/awstats.pl

Did you enjoy this article? Let’s discuss it in the comments below.