Docs Configuration » History » Revision 34
Revision 33 (heavyhttpd, 2009-01-10 13:39) → Revision 34/61 (heavyhttpd, 2009-01-11 04:12)
h1. Configuration file for the core module.
h2. BNF like notation of the basic syntax
<pre>
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
</pre>
*Example*
<pre>
# 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"
</pre>
h2. Conditional Configuration
Most options can be configured conditionally by using the following syntax (including nesting).
<pre>
<field> <operator> <value> {
...
<field> <operator> <value> {
... nesting: match only when parent match
}
}
else <field> <operator> <value> {
... the "else if" block
}
</pre>
where <field> is one of one of the following:
|_.Field name|_.Description|
|$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(optional) and port a port number. 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:
|_.Operator|_.Value|
|==|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:*
<pre>
# 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 = ( "" )
}
}
}
</pre>
h2. 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 <pre>"(^|\\.)example\\.org$"</pre> to <pre>"(^|\\.)example\\.org(\\:[0-9]*)?$"</pre>
Note that some earlier versions of lighttpd do not support the full configuration file syntax listed here. In particular, some versions do not support "var." variables, appending with "+=", nested conditionals, or "else" blocks. The names of some options (for example, "server.dir-listing") have also changed (i.e. to "dir-listing.activate") between versions of lighttpd.
If you're having trouble configuring lighttpd, consider using the "-t" or "-p" options to debug your configuration. Note that some earlier versions of lighttpd not support the "-t" or "-p" options.
h2. Advanced usage
Check the blog: http://blog.lighttpd.net/articles/2005/05/07/advanced-configuration-in-up-upcoming-1-4-x
h2. Using variables
You can set your own variables in the configuration to simplify your config.
<pre>
var.basedir = "/home/www/servers/"
$HTTP["host"] == "www.example.org" {
server.name = "www.example.org"
include "incl-base.conf"
}
</pre>
In incl-base.conf:
<pre>
server.document-root = basedir + server.name + "/pages/"
accesslog.filename = basedir + server.name + "/logs/access.log"
</pre>
You can also use environment variables or the default variables var.PID and var.CWD:
<pre>
var.basedir = env.LIGHTTPDBASE
$HTTP["host"] == "www.example.org" {
server.name = "www.example.org"
include "incl-base.conf"
include "incl-fastcgi.conf"
}
</pre>
In incl-fastcgi.conf:
<pre>
fastcgi.server = ( ... => ((
"socket" => basedir + server.name + "/tmp/fastcgi-" + PID + ".sock"
)) )
</pre>
Or like the lighttpd script for rails does:
<pre>
var.basedir = var.CWD
server.document-root = basedir + "/public/"
</pre>
Some useful things that can NOT be done in lighttpd config (you need to create a script in a real programming language and than use include_shell):
<pre>
# testing if a variable has been set is NOT possible
var.not_sure_if_it_exists == undefined { ... set to default value ... }
# removing from arrays is NOT possible
server.modules -= ( "mod_idontwantyou" )
</pre>
h2. Using Pattern Substitutions
If you use a regex conditional such as:
<pre>
$HTTP["host"] =~ "^([^.]+)\.([^.]+)\.example\.com(:[0-9]+)?$" {
accesslog.filename = "/var/log/www/%1.%2.example.com/access.log"
}
</pre>
Parenthesized subexpressions from the conditional regex can be substituted using patterns begining with "%". %1 is replaced with the first subexpression, %2 with the second, etc. %0 is replaced by the entire substring matching the regexp. So if, for example, $HTTP["host"] is "foo.bar.example.com:8080"
<pre>
%1 would be "foo"
%2 would be "bar"
%3 would be "8080"
%0 would be "foo.bar.example.com:8080"
acesslog.filename would be "/var/log/www/foo.bar.example.com/access.log"
</pre>
h2. Global context
<pre>
global {
...
}
</pre>
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:
<pre>
server.modules = ()
$HTTP["host"] == "www.example.org" {
include "incl-php.conf"
}
</pre>
In incl-php.conf:
<pre>
global {
server.modules += ("mod_fastcgi")
static-file.exclude-extensions += (".php")
}
fastcgi.server = "..."
</pre>
h2. Options
All Configuration Options can be found at: http://trac.lighttpd.net/trac/wiki/Docs%3AConfigurationOptions