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";

BestPracticeTipsForm edit

Category Installation and Upgrading
Related Topics
Topic attachments
I Attachment Action Size Date Who Comment
include-vhosts.pl.txttxt include-vhosts.pl.txt manage 1 K 17 Mar 2013 - 10:57 MichaelDaum  
lightygraphEXT lightygraph manage 5 K 15 Mar 2013 - 12:52 MichaelDaum  
rewrite.confconf rewrite.conf manage 156 bytes 16 Mar 2013 - 11:01 MichaelDaum  
rewrite.lualua rewrite.lua manage 976 bytes 16 Mar 2013 - 11:01 MichaelDaum  
Topic revision: r8 - 28 Jan 2015, GeorgeClark - This page was cached on 29 Jun 2016 - 09:13.

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. See Copyright Statement. Creative Commons License