Lighttpd Version Switch Howto (1.4->1.5)

Lighttpd is a neat web server, small footprint’ed yet full-featured is suitable for use in embedded system. There are two interesting features that make it an ideal choice for a large number of applications – the fastcgi (for php and python server side scripting) and SSL support. Current stable version is 1.4.18 while latest unstable version is 1.5.0-r1992 (things keep changing everyday so you may want to check their site for latest updates). Unfortunately the new version is not fully compatible at configuration level with the previous one. I’ll describe how to adapt the old configuration file for the new version.
In my experience (if a morning of sweating at the bast*rd could be called “experience”) there are two sources of troubles – fastcgi and cgi. Maybe there are more, but solving those two was enough for my needs.
First CGI. There isn’t anything new, but the configuration file. If you look into your old lighttpd.conf you are likely to find something like:

  $HTTP[["url"] =~ "^/cgi-bin" {
    cgi.assign = ( "" => "" )
  }

That syntax is no longer supported, just remove (or comment out) those lines and insert:

  $PHYSICAL[["existing-path"] =~ "^/var/www/myvhost/cgi-bin/" {
    cgi.execute-all = "enable"
  }

Note that before you had just the path in the URL, while now you have to specify the file system path. Also note that “existing-path” is literally that string, do not substitute it, just change the “/var/www/myvhost/cgi-bin/” with the proper value for your system.
The fastcgi is a bit more convoluted because they changed entirely the underlying model. The idea of fastcgi is to keep the CGI processor running so that both startup and shutdown time for the processor are avoided at all. That means big gains for the average http server where lot of shot transactions could ignite one or more invocation for the CGI processor.
Lighttpd 1.5 choses to keep the burden of managing a pool of CGI processors out of the web server itself. In this way managing fastcgi is not that different from behaving like a proxy – a request is received, rewritten and sent to another entity which in turn is expected to answer and the answer is sent back to the original requester.
Anyway this means that you have some external mean to spawn and manage all those pesky php instances. So the action is twofold – first modify the lighttpd configuration, then modify the way lighttpd fires up so to start the pool manager, too.
First the configuration file. You have to remove the old mod_fastcgi from the server.modules list and replace it with the new list:

server.modules = (
  #...
  "mod_proxy_core",
  "mod_proxy_backend_http",
  "mod_proxy_backend_fastcgi",
  # ...
)

Then remove the section that talks about fastcgi.server and may look like this:

# for php
  fastcgi.server = ( ".php" => ((
  "bin-path" => "/usr/sbin/php-cgi",
  "socket" => "/tmp/php.socket",
)))

Replace with:

$PHYSICAL[[ "existing-path" ] =~ ".php$" {
  proxy-core.balancer = "round-robin"
  proxy-core.protocol = "fastcgi"
  proxy-core.allow-x-sendfile = "enable"
  proxy-core.backends = ( "unix:/tmp/php-fastcgi.sock" )
  proxy-core.max-pool-size = 16
  proxy-core.rewrite-request = ( "_pathinfo" => (".php(/.*)" => "$1" ))
}

Here also the “existing-path” string is literally that string, do not substitute.
Now you can close the lighttpd.conf and turn your attention to the launching script. It could be somewhere in /etc/init.d or /etc/rc.d/init.d according to your flavour of linux. Anyway, down there is a lighttpd shell script that accepts one argument such as start, stop, reload or restart. You have to modify it so that before launching the lighttpd deamon a line like the one below is executed:

  /usr/bin/spawn-fcgi -s /tmp/php-fastcgi.sock -f /usr/bin/php-cgi -u webuser -g webgroup -C 5 -P /var/run/spawn-fcgi.pid

spawn-fcgi is the spool manager and is distributed with lighttpd, so you should look for it in the path where lighttpd itself is installed. php-cgi could be located elsewhere, just check your file system and modify accordingly. webuser and webgroup are respectively the user and the group used to run the web server. They are very distribution dependent, you can find them likely in the lighttpd.conf file, just look for the strings after server.username and server.groupserver.
Last, you have to shutdown the spawn-fcgi daemon right after the lighttpd is stopped. You can simply do:

  killall php-cgi

But this could be overkilling if there are other services on the computer that rely on php-cgi for their work. I suspect you can safely look in the /var/run/spawn-fcgi.pid file a kill that pid, but I haven’t tried yet.
I have to credit this FreeBSD related article for cutting through the most obscure aspect of the fastcgi stuff and the lighttpd documentation for the cgi matter.
Enjoy!

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.