Configuration File

Module: core

Table of Contents

• Description
  • Basic Syntax
  • Example
• Conditional Configuration
  • Example
  • Troubleshooting
• advanced usage
• Using variables
• Global context
  • Example
• Options

Description

Basic Syntax

A BNF like notation:

option   : NAME = VALUE
merge    : NAME += VALUE
NAME     : modulename.key
VALUE    : ( <string> | <integer> | <boolean> | <array> | VALUE [ + VALUE ]*)
<string> : "text"
<integer>: digit*
<boolean>: ( "enable" | "disable" )
<array>  : "(" [ <string> "=>" ] <value> [, [ <string> "=>" ] <value> ]* ")"
INCLUDE  : "include" VALUE
INCLUDE_SHELL : "include_shell" STRING_VALUE

Example

# default document-root
server.document-root = "/var/www/example.org/pages/"

# TCP port
server.port = 80

# selecting modules
server.modules = ( "mod_access", "mod_rewrite" )

# variables, computed when config is read.
var.mymodule = "foo"
server.modules += ( "mod_" + var.mymodule )
# var.PID is initialised to the pid of lighttpd before config is parsed

# include, relative to dirname of main config file
include "mime.types.conf"

# read configuration from output of a command
include_shell "/usr/local/bin/confmimetype /etc/mime.types"

Conditional Configuration

Most options can be configured conditionally by using the following syntax (including nesting).

<field> <operator> <value> {
  ...
  <field> <operator> <value> {
    ... nesting: match only when parent match
  }
}
else <field> <operator> <value> {
  ... the "else if" block
}

where <field> is one of one of the following:

$HTTP["cookie"]

match on cookie

$HTTP["host"]

match on host

$HTTP["useragent"]

match on useragent

$HTTP["referer"]

match on referer

$HTTP["url"]

match on url. If there are nested blocks, this must be the most inner block.

$HTTP["querystring"]

match on querystring, eg, after the ? in this type url: index.php?module=images..

$HTTP["remoteip"]

match on the remote IP or a remote Network (Warning: doesn't work with IPv6 enabled)

$HTTP["scheme"] (Introduced in version 1.4.19)

match on the scheme used by the incoming connection. This is either "http" or "https".

$SERVER["socket"]

match on socket. Value must be on the format "ip:port" where ip is an IP address and port a port number, or ":port" to match port only. Only equal match (==) is supported. It also binds the daemon to this socket. Use this if you want to do IP/port-based virtual hosts.

$PHYSICAL["path"] (Introduced in version 1.5.0)

match on the mapped physical path of the file / cgi script to be served.

$PHYSICAL["existing-path"] (Introduced in version 1.5.0)

match on the mapped physical path of the file / cgi script to be served only if such a file exists on the local filesystem.

<operator> is one of:

==

string equal match

!=

string not equal match

=~

perl style regular expression match

!~

perl style regular expression not match

and <value> is either a quoted ("") literal string or regular expression.

Example

# disable directory-listings for /download/*
dir-listing.activate = "enable"
$HTTP["url"] =~ "^/download/" {
  dir-listing.activate = "disable"
}

# handle virtual hosting
# map all domains of a top-level-domain to a single document-root
$HTTP["host"] =~ "(^|\.)example\.org$" {
  server.document-root = "/var/www/htdocs/example.org/pages/"
}

# multiple sockets
$SERVER["socket"] == "127.0.0.1:81" {
  server.document-root = "..."
}

$SERVER["socket"] == "127.0.0.1:443" {
  ssl.pemfile = "/var/www/certs/localhost.pem"
  ssl.engine = "enable"

  server.document-root = "/var/www/htdocs/secure.example.org/pages/"
}

# deny access for all googlebot
$HTTP["useragent"] =~ "Google" {
  url.access-deny = ( "" )
}

# deny access for all image stealers (anti-hotlinking for images)
$HTTP["referer"] !~ "^($|http://www\.example\.org)" {
  url.access-deny = ( ".jpg", ".jpeg", ".png" )
}

# deny the access to www.example.org to all user which
# are not in the 10.0.0.0/8 network
$HTTP["host"] == "www.example.org" {
  $HTTP["remoteip"] != "10.0.0.0/8" {
   url.access-deny = ( "" )
  }
}

# Allow only 200.19.1.5 and 210.45.2.7 to
# have access to www.example.org/admin/
$HTTP["host"] == "www.example.org" {
  #!~ is a perl style regular expression not match
  $HTTP["remoteip"] !~ "^(200\.19\.1\.5|210\.45\.2\.7)$" {
    $HTTP["url"] =~ "^/admin/" {
      url.access-deny = ( "" )
    }
  }
}

Troubleshooting

If you're not running on the default port, $HTTP["host"] will have the port appended to it, so regular expressions ending in "$" (without allowing for a port) won't match. To match with or without a port, change "(^|\.)example\.org$" to "(^|\.)example\.org(\:[0-9]*)?$"

advanced usage

check the blog: http://blog.lighttpd.net/articles/2005/05/07/advanced-configuration-in-up-upcoming-1-4-x

Using variables

You can set your own variables in the configuration to simplify your config.

var.basedir = "/home/www/servers/"
$HTTP["host"] == "www.example.org" {
   server.name = "www.example.org"
   include "incl-base.conf"
}

in incl-base.conf:
server.document-root = basedir + server.name + "/pages/"
accesslog.filename   = basedir + server.name + "/logs/access.log"

You can also use environment variables or the default variables var.PID and var.CWD:

var.basedir = env.LIGHTTPDBASE

$HTTP["host"] == "www.example.org" {
   server.name = "www.example.org"
   include "incl-base.conf"
   include "incl-fastcgi.conf"
}

in incl-fastcgi.conf:
fastcgi.server = ( ... => ((
   "socket" => basedir + server.name + "/tmp/fastcgi-" + PID + ".sock"
)) )

Or like the lighttpd script for rails does:

var.basedir = var.CWD

server.document-root = basedir + "/public/"

Global context

global {
  ...
}

You don't need it in the main configuration file. But you might have difficulty setting a server wide configuration inside a included-file from conditionals.

Example

in lighttpd.conf:
server.modules = ()
$HTTP["host"] == "www.example.org" {
  include "incl-php.conf"
}

in incl-php.conf:
global {
  server.modules += ("mod_fastcgi")
  static-file.exclude-extensions += (".php")
}
fastcgi.server = "..."

Options

All Configuration Options