Getting Lighttpd working with AWStats

Following my previous post about configuring Lighttpd on this VPS Webserver to replace Apache I bring you a guide to configuring AWStats under Lighttpd. This process is differs to Apache as control of directories and aliasing is handled differently. There can also be complications if you have previously enabled the Drupal LUA Magnet script on your site for clean URL handling!

Firstly, lets define a few things…

  • AWStats wwwroot is /usr/share/awstats/wwwroot (the folder which contains the cgi-bin and icon folders
  • AWStats configuration files are in /etc/awstats.
  • I have downloaded, and placed in my cgi-bin folder, awstatstotals.php.


Ok, firstly I want to add the following to my Lighttpd configuration…

alias.url += (
  "/js/awstats_misc_tracker.js" => "/usr/share/awstats/wwwroot/js/awstats_misc_tracker.js"

$HTTP["url"] =~ "^/awstats" {
  alias.url += (
    "/awstats/"      => "/usr/share/awstats/wwwroot/cgi-bin/",
    "/awstatsicons/" => "/usr/share/awstats/wwwroot/icon/",

  global {
    server.modules += ( "mod_cgi", "mod_auth" )

  $HTTP["remoteip"] !~ "" {
    # Configure Authentication
    auth.debug = 2
    auth.backend = "plain"
    auth.backend.plain.userfile = "/path/to/passwords/file"

    # We've already restricted the folder
    auth.require = ( "" => (
        "method" => "basic",
        "realm" => "Stats Area",
        "require" => "valid-user",

  index-file.names = ( "awstatstotals.php" )

  cgi.assign = (
    ".pl" => "/usr/bin/perl",
    ".cgi" => "/usr/bin/perl"
  magnet.attract-physical-path-to = ()

Lets have a run through this…

  • The first url.alias simply tells Lighttpd to globally create an alias of that javascript file for all sites. This allows those sites to have AWStats track a little more information about the visitor. This also saves us copying it into a folder for every website.

  • Next up we have a line which tells Lighttpd to ONLY apply the following settings for pages served within "/awstats". The initial '^' is regular expression for begins with.

  • Next up we define 2 new alises. These aliases ONLY apply for requests from within the path "/awstats". The first points the "/awstats" path to the AWStats cgi-bin folder. The other aliases the icons folder. This is necesary as we have made the cgi-bin folder the "root". We could get away with just one alias if we made the wwwroot folder the root instead… but we haven't :-)

  • Next up we enable some modules. The mod_cgi module is useful if you wanna run things like Perl scripts. The other module, mod_auth, is useful if you wanna protect your folder with a password. I don't know this for certain, but I'd hazard a guess that these modules only get loaded for this particular path. I'm not sure though, cant find any documentation implying or proving either way.

  • Next up we do some permissions. In this case I would mostly be accessing the stats from the IP (yes, this IS an example!), so I want to tell Lighttpd to ONLY run the access deny check if the remote IP isn't this example. I've done it as a RegEx right now so it will be easy for me add other IPs to exclude authorization from in the future. Within this we enable and configure the Lighttpd Mod Auth Settings.

  • Next up we tell Lighttpd to use the awstatstotals.php script as the index file. This provides me with a nice monthly, server-level overview of stats. Its quite handy!

  • Almost there… We now tell Lighttpd some CGI settings (for mod_cgi). Here, we teach it what applications to associate with given file extensions.

  • The final Magnet line is one I have to put in as I'm running a Drupal site. In the one of the following posts I will explain how I got Drupal running on Lighttpd - but for now suffice to say that you need to tell Lighttpd to use a funky LUA script to get the Clean URL's working. I believe this is to do with telling it to serve non-existant URL's via Drupal's "q" argument.

Thats about it guys! Once I got it working, it was pretty simple.

Oh - one final hint… Make sure you enable mod_alias BEFORE you go onto the Lighttpd IRC chat and ask why your aliases aren't working. This tip was brought to you by "the guy who feels really stupid for asking a question which doesn't really need asking".