While this document outlines the steps required to install awstats for a new server and for virtual hosts, this process can take several dozen minutes. By the time one locates the documentation, reviews the steps required, creates the directories, edits the config files, etc..., a lot of time can be wasted. To accommodate the rapid addition of the services of awstat to a new virtual host, this tool was created.

The tool was developed on a GNU/linux, RedHat 7.1 system, and is now running on a Slackware box, but has not been tested on other systems. Most of the configuration settings, especially file names and paths, have been localized to the top of the file for easy modification. The script is heavily documented for easy understanding, and the procedure that it automates is completely outlined here, but this document will explain its usage and operation.

For those of you who use ISPMan, have a look at Wim Kerkhoff's web site. He has some tools to make your life easier.

Top of Page

The program may be installed anywhere in root's path; location doesn't matter. It expects a single argument, the virtual host name. For example:

/root/bin/awstats4vhost www.virtualhost.com

The program will output nothing but a message upon completion naming the log file containing a complete description of changes made, and the contents of changed files. This file should be carefully inspected for errors. Note that the program will refuse to run if this file exists. This feature prevents overwriting the output of previous runs. Simply delete the file, or rename before calling the program. By default, this file is /root/install.awstats4host.out

All diagnostic output from subprocesses is captured in this file, also. Errors such as missing directories can be diagnosed, and progress assessed before attempting to rerun the program. Note that any edits made to configuration files will not be undone in the event of errors. Be very careful about multiple runs for the same virtual host.

The URL for the awstats output will be:

http://some.domain.com/cgi-bin/awstats.pl

Top of Page

1. The program can only be run by root. Sufficient privileges are required to write to system directories not normally writable by lesser mortals.
2. Original installation files are expected to reside in /opt/awstats. This is the default installation location from the awstats installation.
3. Apache configuration and log files are expected to have the virtual host name as a prefix. For example, /etc/httpd/conf/include/capella.ithaca.ny.us.conf and /var/log/httpd/capella.ithaca.ny.us_access_log. The use of included files for virtual hosts eases administration burdens. See the apache documentation for more details.
4. awstats configuration files live in /etc/awstats. Each file has the virtual host name prepended just as with the apache config files:
   /etc/awstats/awstats.capella.ithaca.ny.us.conf
5. A general-purpose config file sans a few specific items lives in the awstats config directory and is included by the program:
   /etc/awstats/awstats.headless.conf
6. Each virtual host has its own data directory beneath the default, /var/cache/awstats.
7. /etc/cron.hourly/awstats is updated for each virtual host. It runs awstats hourly. This seems to be about right for the various sizes of hosts that we have observed. This file must already exist.
8. The program installs awstats files in a top-level directory beneath the site's DocumentRoot. For example, if the root is /var/www/some.domain.com, the destination will be /var/www/some.domain.com/awstats.
9. The program expects the cgi-bin directory to live right beneath the site's DocumentRoot. Using the previous example, that would be /var/www/some.domain.com/cgi-bin.
10. Apache is restarted after the installation so that it will reread its configuration and pick up the new alias to the awstats directory.
11. An initial run is not started since cron will cause this to happen within the next hour.

Top of Page

These files may be obtained by downloading this tarball.

1. awstats4vhost - Bourne shell script
2. /etc/awstats/awstats.headless.conf - awstats configuration template
3. /etc/cron.hourly/awstats - system cron job
4. index.html - this file
5. vhosts.html - step by step procedure for setting up a new server and configuring addtional virtual hosts with awstats

Top of Page