Awstats "how to" (static generated reports)

Home

AWStats is an open source Web analytics reporting tool, suitable for analyzing data from Internet services such as web, streaming media, mail and FTP servers. AWstats parses and analyzes server log files, producing HTML reports. Data is visually presented within reports by tables and bar graphs. Static reports can be created through a command line interface, and on-demand reporting is supported through a web browser CGI program.

AWStats supports most major web server log file formats including Apache (NCSA combined/XLF/ELF log format or common/CLF log format), WebStar, IIS (W3C log format) and many other common web server log formats. Developers can contribute to the AWStats project through SourceForge.

AWStats is a free powerful and featureful tool that generates advanced web, streaming, ftp or mail server statistics, graphically. This log analyzer works as a CGI or from command line and shows you all possible information your log contains, in few graphical web pages. It uses a partial information file to be able to process large log files, often and quickly. It can analyze log files from all major server tools like Apache log files (NCSA combined/XLF/ELF log format or common/CLF log format), WebStar, IIS (W3C log format) and a lot of other web, proxy, wap, streaming servers, mail servers and some ftp servers. Awstats

Written in Perl, AWStats can be deployed on almost any operating system. It is a very popular server administration tool, with packages available for most Linux distributions. AWStats can be installed on a workstation, such as MS Windows, for local use in situations where log files can be downloaded from a remote server.

Avoiding CGI: Static generation compared to CGI

We will be using AWStats in static generation mode. This means that all the pages will be built when the cron job runs, not when a user visits the AWStats web page.

The on-demand CGI program has been the object of security exploits, as is the case of many CGI programs. Organizations wishing to provide public access to their Web analytics reports should consider generating static HTML reports.

Starting the install

Step 1: The download : Download the latest tarball of Awstats from the Awstats download page.

Step 2: Untar : Once the tarball is downloaded you need to decide where you want the Perl scripts and tools to be located. We will be using the directory we made called /webstats . This directory is not under the web tree, just somewhere we can put web tools. In this directory you can untar the awstats tar.gz file. Then re-name the untared directory from "awstats-X.X" to just "awstats" for simplicity.

cd /webstats
tar zxvf awstats-6.7.tar.gz
mv awstats-6.7 awstats

Step 3: Run the config : We now need to run the Perl script located under the awstats directory in "tools/awstats_configure.pl". This script will help you configure some basic options and also make the site configuration file for you. Run "awstats_configure.pl" and answer the questions it asks. Here are the questions and answers we have for this example:

For our example we will be using the url "SITE_NAME.COM". You should put your URL in place of this string. We used upper case characters to make it easy to see, but you can use lower case as well.

Do you want to continue setup from this NON standard directory [yN] ? y
Config file path ('none' to skip web server setup): none
Do you want me to build a new AWStats config/profile file (required if first install) [y/N] ? y
Your web site, virtual server or profile name: SITE_NAME.COM
Directory path to store config file(s): /webstats/awstats/wwwroot/cgi-bin/

Step 4: Edit the config : The site config file called "awstats.SITE_NAME.COM.conf" is now located in /webstats/awstats/wwwroot/cgi-bin/ . Lets edit the file now. We kept all of the default options other than those listed below:

LogFile="/var/log/web_server/access.log"
SiteDomain="SITE_NAME.COM"
HostAliases="SITE_NAME.COM www.SITE_NAME.COM 127.0.0.1 localhost"
DNSLookup=1
DirData="/webstats/awstats/"
DirIcons="/htdocs/awstats/icon"

Step 5: Make the web tree : The web tree for awstats now needs to be made. Lets use the standard /var/www/htdocs/ as our web root. Make a directory under web root called "awstats".

mkdir /var/www/htdocs/awstats/

Now, we also need the icons from awstats to be located under the web tree. Recursively copy the "wwwroot/icon/" directory to "/var/www/htdocs/awstats/.

cp -R /webstats/awstats/wwwroot/icon/ /var/www/htdocs/awstats/

Step 6: Generate the stats : The last task is to run the stats build utility ans tell Awstats were to put the HTML files. The following line will:

Execute the perl script /webstats/awstats/tools/awstats_buildstaticpages.pl
-awstatsprog tells "awstats_buildstaticpages.pl" where "awstats.pl" is found
-update executes a refresh on the web pages
-config=SITE_NAME.COM uses the config file called "awstats.SITE_NAME.COM.conf"
-dir=/var/www/htdocs/awstats/ is where the HTML pages are to be put

Here is the commands in a single line. We suggest putting this line into a file as a shell script for ease of use.

perl /webstats/awstats/tools/awstats_buildstaticpages.pl -awstatsprog=/webstats/awstats/wwwroot/cgi-bin/awstats.pl -update -config=SITE_NAME.COM -dir=/var/www/htdocs/awstats/

Looking at the resulting HTML

Congratulations. You can now point your browser to your web server and see your generated stats.

http://www.SITE_NAME.COM/awstats/awstats.SITE_NAME.COM.html

Generating the reports with Cron

To automate the process of building new Awstats reports lets use cron. The following example will run the above perl line every hour to generate the latest HTML pages.

#minute (0-59)
#|   hour (0-23)
#|   |    day of the month (1-31)
#|   |    |   month of the year (1-12 or Jan-Dec)
#|   |    |   |   day of the week (0-6 with 0=Sun or Sun-Sat)
#|   |    |   |   |   commands
#|   |    |   |   |   |
#### rotate logs weekly (Sunday at midnight)
00   *    *   *   *   perl /webstats/awstats/tools/awstats_buildstaticpages.pl -awstatsprog=/webstats/awstats/wwwroot/cgi-bin/awstats.pl -update -config=SITE_NAME.COM -dir=/var/www/htdocs/awstats/

Questions?

Does Awstats run quickly?

The report generator is only as fast as the DNS resolution of the machine. The first time the script is run Awstats will create a DNS cache file and go through all of the lines of the log. Depending on how many lines in the log the scripts can run for many minutes. On the second run of Awstats it will be a lot faster. This is because it only needs to go though only the new line of the logs and most of the DNS query results are already in DNS cache.

What other report generators are there?

At Calomel.org we highly recommend looking at Webalizer. We have a detailed "how to" called Webalizer -- Web Server Statistics (webalizer.conf)

Questions, comments, or suggestions? Contact Calomel.org