Some notes to myself on setting up AWStats on a Gentoo box.

  1. First, emerge the awstats package. I added the "vhosts" USE flag because it's listed as a USE flag that awstats reads, and I need support for virtual hosts (although I don't know for sure what it does - I reckon it has something to do with the webapps-config package that's a dependency).

    emerge -pv awstats
    USE="vhosts" emerge awstats
  2. Don't use the webapp-config program that the emerge process tells you to use at the end unless you know what you are doing. There have been reports that it isn't exactly ideal in the Gentoo forums.

  3. Make a symbolic link to the Apache configuration directives we need to add to Apache in a convenient location. You may also want to make the file owner-writable (chmod u+w) since it's read-only.

    ln -s /usr/share/webapps/awstats/6.1/postinst-en.txt /etc/apache2/conf/awstats.conf
  4. I had to add this bit to /etc/apache2/conf/awstats.conf prevent a 403 error when accessing the ScriptAliased /awstats directory.

    <directory "/usr/share/webapps/awstats/6.1/hostroot/cgi-bin/">
    Options +ExecCGI +FollowSymLinks
    AllowOverride None
    Order allow,deny
    Allow from all</directory>
  5. Include the AWStats-required configuration directives in the main Apache config file (mine's /etc/apache2/conf/apache2.conf).

    Include conf/awstats.conf
  6. I'm using name-based virtual hosts, with logs for each of them (they are in the included vhosts/vhosts.conf file). AWStats by default parses the Combined log format and this is what I specify for my access logs as well. An example VirtualHost directive:

    <VirtualHost *:80>
    ServerName blog.codefront.net
    DocumentRoot /www/codefront.net/htdocs/blog
    ServerPath /blog
    CustomLog /var/log/apache2/blog.codefront.net/access_log combined
    ErrorLog /var/log/apache2/blog.codefront.net/error_log
    </VirtualHost>
  7. Now, create an AWStats configuration file for each virtual-host.

    cp /etc/awstats/awstats.model.conf /etc/awstats/awstats.blog.codefront.net.conf

    Notice that the configuration file name is of the format "awstats.domain.tld.conf".

  8. Edit the configuration file (/etc/awstats/awstats.blog.codefront.net.conf). The important things to change are:

    • LogFile (point this to your access log)
    • SiteDomain (your site's domain name)
    • HostAliases (any aliases your site may have)
    • DirData (AWStats database where your results will be stored. This has to be writable by the Apache user if the AllowToUpdateStatsFromBrowser option is turned on.)
    • DirCgi (AWStats CGI directory)
    • DirIcons (AWStats icons directory)
  9. Restart Apache.

    /etc/init.d/apache2 restart
  10. You can access AWStats from www.example.com/awstats/awstats.pl?config=www.example.com.

  11. Set password-protection for the AWStats directory.

  12. Run AWStats from the command line to update it. You'd likely want to set up a cron job for this.

    /usr/bin/awstats_updateall.pl now -awstatsprog=/usr/share/webapps/awstats/6.1/hostroot/cgi-bin/awstats.pl -configdir=/etc/awstats/

Useful links: