How to configure lighttpd

There are many ways to set up a Foswiki server using lighttpd. This tip covers two methods, starting with the simplest and rising in complexity (and functionality).

Quick and Dirty

The simplest way to run lighttpd is to use the tools/lighttpd.pl perl script shipped with Foswiki. As long as lighttpd is installed, all you have to do is to run this script from the command-line, and it will start a server. This is a good way to get Foswiki up and running quickly, especially if you don't have an existing web server.

Your operating system may have mechanisms to allow such a script to be run in the background when the server starts.

• + simple
• + uses fastcgi if it's available
• - primarily intended for use by developers
• - requires additional configuration if you want anything more than a quick "suck it and see".

Fully-featured installation

Here's how to set up lighttpd for a medium to large Foswiki installation of multiple virtual hosts. This includes:

• fastcgi as well as plain cgi for debugging
• serving compressed css and js files
• short urls
• automation of domain configuration, including server aliasing as configured by VirtualHostingContrib
• protection of attachments using xsendfile (instead of the standard viewfile approach)
• http -> https redirect of login and register

Directory layout

Lighttpd

These are the configuration files used by lighttpd:

File	Description
/etc/lighttpd/rewrite.lua	rewrite requests to css and js files to their gziped version when available
/etc/lighttpd/rewrite.conf	redirect configuration using rewrite.lua
/etc/lighttpd/lightygraph.pl	generates load statistics using rrd
/etc/lighttpd/conf-enabled/10-fastcgi.conf	required module
/etc/lighttpd/conf-enabled/05-auth.conf	required module
/etc/lighttpd/conf-enabled/10-ssl.conf	optional module
/etc/lighttpd/conf-enabled/10-expire.conf	required module
/etc/lighttpd/conf-enabled/10-rrdtool.conf	optional module for load statistics
/etc/lighttpd/conf-enabled/10-cgi.conf	required module
/etc/lighttpd/conf-enabled/10-magnet.conf	required module to run rewrite.lua on some urls
/etc/lighttpd/conf-enabled/20-foswiki.conf	required module
/etc/lighttpd/lighttpd.conf	base configuration as it comes with your distro
/etc/lighttpd/foswiki-base.conf	configuration used by each virtual host
/etc/lighttpd/certs/your-domain.com/host.pem	your ssl certificates
/etc/lighttpd/certs/your-domain.com/...	...
/etc/lighttpd/lighttpd.user	credentials for basic authentication to protect the /server/ path, i.e. /server/configure

Foswiki

Both the Foswiki root and the directory holding all vhosts can be configured in /etc/lighttpd/conf-enabled/20-foswiki.conf and (unfortunately) in

• /var/www/foswiki/lib/LocalSite.cfg
• /var/www/vhosts/_template/VirtualHost.cfg

as well. VirtualHostingContrib needs a

$Foswiki::cfg{VirtualHostingContrib}{VirtualHostsDir} = '/var/www/vhosts';

in LocalSite.cfg.

This one may serve as our example:

Path	Description
/var/www/foswiki	git clone location
/var/www/foswiki/core	foswiki installation
/var/www/foswiki/core/tools/include-vhosts.pl	generates virtual domain configuration found in the vhosts directory
/var/www/foswiki/core/lib/LocalSite.cfg	default foswiki configuration shared by all virtual hosts, per-domain configuration differences are in VirtualHost.cfg; this file is maintained using foswiki's standard configure application via the http://.../server/configure url
/var/www/vhosts/_template/	location of the domain template
/var/www/vhosts/_template/pub
/var/www/vhosts/_template/VirtualHost.cfg	configuration for a virtual domain overlaying /var/www/foswiki/core/lib/LocalSite.cfg
/var/www/vhosts/_template/pub/System	sym link to /var/www/foswiki/core/pub/System
/var/www/vhosts/_template/pub/images	thumnail images generated by ImageGalleryPlugin
/var/www/vhosts/_template/pub/Trash/...	a copy of the default trash as it comes in /var/www/foswiki/core/pub/Trash
/var/www/vhosts/_template/working/...	a copy of the default trash as it comes in /var/www/foswiki/core/working
/var/www/vhosts/_template/html	document root for static html files, e.g. holding a robots.txt and a favicon.ico
/var/www/vhosts/_template/data	holds some symlinks to webs shared among all vhosts as well
/var/www/vhosts/_template/data/_empty	a copy of the default trash as it comes in /var/www/foswiki/core/data/_empty
/var/www/vhosts/_template/data/_default	a copy of the default trash as it comes in /var/www/foswiki/core/data/_default
/var/www/vhosts/_template/data/Sandbox	a copy of the default trash as it comes in /var/www/foswiki/core/data/Sandbox
/var/www/vhosts/_template/data/System	symlink to /var/www/foswiki/core/data/System
/var/www/vhosts/_template/data/Applications	symlink to /var/www/foswiki/core/data/Applications in case you are using WikiWorkbenchContrib to share all wiki apps on all virtual hosts
/var/www/vhosts/_template/data/Trash	a copy of the default trash as it comes in /var/www/foswiki/core/data/Trash
/var/www/vhosts/_template/data/Main	a copy of the default trash as it comes in /var/www/foswiki/core/data/Main
/var/www/vhosts/your.domain.com	location a running domain, initiated as a copy of /var/www/vhosts/_template

Files

20-foswiki.conf

# global vars
var.vhostsdir = "/var/www/vhosts"
var.foswikidir = "/var/www/foswiki/core"
server.breakagelog = "/var/log/lighttpd/error.log"

#debug.log-condition-handling = "enable"
#debug.log-request-header = "enable"
#debug.log-request-handling = "enable"
#debug.log-response-header = "enable"

# See Item12581: Lighttpd lower cases PATH_INFO on case-insensitive file systems.
server.force-lowercase-filenames = "disable"

$HTTP["useragent"] =~ "MSIE" {
  server.max-keep-alive-requests = 0
}

# server maintenance
$HTTP["url"] =~ "^/server/configure" {
  alias.url += ( "/server/configure" => foswikidir + "/bin/configure" )
  cgi.assign = ( "" => "" )
  setenv.add-environment = ( "AUTH_TYPE" => "Basic" ) # "Basic" or "Digest"
}

# optional in case you use rdd tools for load statistics
$HTTP["url"] =~ "^/server/lightygraph" {
  alias.url += ( "/server/lightygraph" => "/etc/lighttpd/lightygraph.pl" )
  cgi.assign = ( "" => "" )
}

include_shell "/etc/lighttpd/include-vhosts.pl"

foswiki-base.conf

This file is included by each domain and makes use of the server variables set before.

include "rewrite.conf"

# redirect login to https
# redirect System.UserRegistration to https
$HTTP["scheme"] == "http" {
  #url.redirect = ( "^/(.*)" => "https://" + server.name + "/$1" )
  url.redirect += ( 
    "^/((?:bin/)?(?:login).*)" => "https://" + server.name + "/$1",
    "^/(?:bin/view/)?(System/UserRegistration)" => "https://" + server.name + "/$1"
  )
}

# enable this one to protect your wiki apps 
#url.redirect = ( "^/+(bin\/+view\/+)?Applications.*" => "http://" + server.name )

# short urls
url.rewrite-once += ( "^/?(\?.*)?$" => "/bin/view" )
url.rewrite-once += ( "^/([A-Z_].*)" => "/bin/view/$1" )

# protect attachments
# exceptions:
#   * System
#   * Applications
#   * Sandbox
#   * thumbnails
#   * !GenPDFPrincePlugin drags in css, js and image files via localhost so no authentication is required then
$HTTP["useragent"] !~ "Prince" {
   url.rewrite-once += ( "^/pub/((?!System|Application|images|Sandbox).*)/(.*?)$" => "/bin/xsendfile/$1/$2" )
}

# alias for /pub
$HTTP["url"] =~ "^/pub/" {
  expire.url += ("/pub" => "access 8 hours")
  alias.url += ("/pub" => vhostsdir + "/" + server.name + "/pub" )
}

# fcgi for anything bin
$HTTP["url"] =~ "^/bin/" {
  alias.url += ( "/bin" => foswikidir + "/bin/virtualhosts.fcgi" )

  fastcgi.server = ( ".fcgi" => ((
      "socket"    => foswikidir + "/working/tmp/virtualhosts.sock",
      "bin-path"  => foswikidir + "/bin/virtualhosts.fcgi",
      "check-local" => "disable",
      "idle-timeout" => 20,
      "min-procs" => 4,
      "max-procs" => 10,
      "allow-x-send-file" => "enable"
    ),
  ))

  expire.url = ( )
}

# optionally access your sites using plain cgi via =http://your-domain.com/cgi-bin/Web/Topic
# usefull for debugging
$HTTP["url"] =~ "^/cgi-bin/" {
  alias.url += ( "/cgi-bin" => foswikidir + "/bin/virtualhosts" )
  cgi.assign = ( "" => "" )
  setenv.add-environment = ( "FOSWIKI_ASSERTS" => "1" )
}

# add an extra expire header to xsendfile
$HTTP["url"] =~ "^/bin/(viewfile|xsendfile)" {
  expire.url = ( "" => "access 8 hours")
}

05-auth.conf

This one protects anything under http://...//server by using a basic auth. It references digests stored in /etc/lighttpd/lighttpd.users which you need to generate using the htdigest command.

server.modules += ( "mod_auth" )

auth.backend = "htdigest"
auth.backend.htdigest.userfile  = "/etc/lighttpd/lighttpd.user"
#auth.backend.htdigest.groupfile = "/etc/lighttpd/lighttpd.group"
auth.debug = 0

auth.require = ( 
  "/server" => (
    "method"  => "basic",
    "realm"   => "your domain realm",
    "require" => "user=admin" 
  )
)

10-ssl.conf

$SERVER["socket"] == "0.0.0.0:443" {
  ssl.engine  = "enable"
  ssl.pemfile = "/etc/lighttpd/certs/your.domain.com/host.pem"
}

10-rrdtool.conf

server.modules += ( "mod_rrdtool" )

## path to the rrdtool binary
rrdtool.binary   = "/usr/bin/rrdtool"

## file to store the rrd database, will be created by lighttpd
rrdtool.db-name   = "/var/cache/lighttpd/lighttpd.rrd"

VirtualHost.cfg

The one im /var/vhosts/_template/VirtualHosts.cfg looks like this. Note that you'll have to adjust the domain name when creating a new host.

my $domain = "your.domain.com";

$VirtualHost{DefaultUrlHost} = "https://$domain";
$VirtualHost{PermittedRedirectHostUrls} = "http://$domain, https://$domain";

# in case you are using a solr core per domain
$VirtualHost{SolrPlugin}{Url} = "http://localhost:8080/solr/$domain";

# note this has to match the vhost directory as configured above
$VirtualHost{XSendFileContrib}{Location} = "/var/www/vhosts/$domain/pub";