Main Configuration

Boolean

There are two boolean values:

• true
• false

Integers

Integers are stored as signed ints with 64 bits (max value around 9 * 10^18). There are three basic ways to use them:

• decimal integers: starting with any non zero digit, like 128
• octal integers: starting with a zero, like 0644
• hexadecimal integers: starting with 0x like 0xff

All three can have a suffix representing a factor the number gets multiplied with:

• byte: 1
• kbyte: 1024
• mbyte: 1024*1024
• gbyte: 1024*1024*1024
• tbyte: 1024*1024*1024*1024
• pbyte: 1024*1024*1024*1024*1024
• bit: 1 / 8
• kbit: 1024 / 8
• mbit: 1024*1024 / 8
• gbit: 1024*1024*1024 / 8
• tbit: 1024*1024*1024*1024 / 8
• pbit: 1024*1024*1024*1024*1024 / 8
• sec: 1
• min: 60
• hours: 3600
• days: 24*3600

For sizes the base unit is byte, and for intervals seconds.

Strings

There are 4 ways to specify a string:

• 'hello world'
• "hello world"
• e'hello world'
• e"hello world"

The basic escape rules are the same for both:

• "\n" is a newline, "\r" a carriage return, "\t" a tab stop
• "\\" is one \, "\"" is one double quote " and "\'" a single quote '
• escaping single/double quote is optional if the symbol is not used to terminate the string, i.e. '\"' = '"' and "\'" = "'"
• "\xNN": NN must be hexadecimal characters, and the string is replaced with the decoded 8-bit value as a single byte
• All other \ occurences are not removed from the string.

The e'..' and e"..." variant do not allow any occurences of the last kind to happen.

All other characters are allowed (the strings are parsed as 8-bit binary; lighttpd2 usually doesn’t care about the encoding).

Lists

Lists are ordered collections of other values:

• [1, true, "foo"] (simple list)
• [] (empty list)
• [1] (list with one element)
• [[1,2],[3,4],5] (nested lists)
• [1,2,] (final value can have a trailing , too)
• (1, 2, 3) (alternative brackets with more than one element)

Note that (1) is not a list; parentheses can also be used to group expressions as in 1*(2+3), and it is therefore recommend to use only [] to specify lists.

Key-Value Lists

Key-value lists associates keys to values (both can be of any type); the syntax is:

• [ "a" => 1, "b" => 10 ]

As with normal lists the final value can have a trailing , too. You cannot mix simple values and key-value associations in one list (nesting them works).

The key => value operator is also only syntactic sugar for a [key, value] list, the above example is the same as:

• [ [a, 1], [b, 10] ]

This especially means that key-value lists are ordered too, although they can get converted to hash tables in certain function calls internally.

Expressions

There are operators available for some value types:

• for integers: +, -, * and /
• for strings: + (concatenate two strings)
• for lists: + (append lists)

Also you can cast strings and booleans to integers and any value to strings:

• cast(int) "256" (only supports decimal representations and no suffix like above)
• cast(int) true (true maps to 1 and false to 0)
• cast(string) 5

Expressions can be grouped to override default association:

• 3 * (1 + 2) vs. 3 * 1 + 2 and so on

Action Blocks

An action block consists of a list of function calls (in action context) and conditionals; it is treated like a value, i.e. can be assigned to variables and used as parameter in function calls.

Action blocks can also contain variable assignments and setup blocks/function calls, which are not part of the “action block value” itself, but are evaluated while parsing the config.

The syntax is:

{ log "hello world"; if req.path =$ ".hidden" { static; } }

The complete config is an action block too (but without the surrounding curly braces); conditionals also use action blocks for their branches.

Each action block that is not a condition branch starts a new nested variable scope;

Variables

Variable names start with a alphabetic character (a-z and A-Z) or an underscore _, and are followed by alphanumeric characters, underscores _ and dots .; keywords are not allowed as variable names.

Variables store values, and the name can be used in place of an actual value; later modifications to a variable have no influence on previous uses (i.e. are only evaluated while parsing the config).

Variables are assigned values with = (and a terminating ;)

my_types = [".txt" => "text/html"]; php = { if phys.path =$ ".php" { fastcgi "unix:/var/run/lighttpd/php.sock"; } };

By default variables assignment overwrites an existing variable (in its previous scope) or, if it doesn’t exist, creates a new one in the local scope (i.e. it will only be available in the current scope and nested descendants).

You can explicitly create a new variable in the local scope (hiding variables in parent scopes with the same name) by prefixing the assignment with local:

local wwwpath = "/var/www/example.com";

You can also create variables in the global scope by prefixing the assignment with global.
The main config already is in a nested scope (i.e. not the global scope). The global scope is not destroyed after config loading, and can be used in delayed config loading (say from SQL in the future).

If a variable name is used in a context it will always use the definition from the nearest scope.

foo = "bar";
if req.path == "/somepath" {
	foo = "baz";
}

# at this point foo will ALWAYS contain "baz" no matter if "/somepath" was requested or not

foo = "bar";
php = {
	local foo = "baz";
	# in this block (and nested blocks within) foo is now "baz"
	# ...
};
# foo is now "bar" again

Special Variables

sys.* variables are readonly. right now the following sys.* variables are available:

• sys.pid: the process id of lighttpd
• sys.cwd: the current working directory
• sys.env.X: the system environment variable with name X (for any X)

Includes

Includes are similar to function calls in the syntax, but are directly handled by the config parser. They are only allowed in action context, as they insert a reference to an action block at the point they are used.

There are three types of includes:

• include "/etc/lighttpd/vhosts/*.conf";: include files like the main config itself; the path can contain wildcards
• include_shell "/etc/lighttpd/config_generator.sh";: runs the specified command, and parses the output of it as config file
• include_lua "/etc/lighttpd/complex.lua": includes a Lua config file. The single action to be executed must be returned in the global actions variable (or leave it empty to do nothing). See also lua.handler.

Includes also create a new nested scope.

Debug Print

Similar to includes __print is a special function, but is available in action and setup context. It logs the string values of its parameter(s) with log level “debug”.

Syntax

The basic syntax forms are:

• if <expr> { ... }
• if <expr> { ... } else { ... }
• if <expr> { ... } else if <expr2> { ... }
• if <expr> { ... } else if <expr2> { ... } ... (continue with else or else if)

A condition expression <expr> is:

• (<expr>)
• <expr1> and <expr2>
• <expr1> or <expr1> (<expr1> and <expr2> or <expr3> = (<expr1> and <expr2>) or <expr3>; and has higher precedence)
• <condvar> <op> <value> for <condvar> being a condition variable (with a type different from boolean), <op> an condition operator and <value> a string or a number.
• <condvar> or !<condvar> for a boolean condition variable.

Condition variables

There are three categories of condvars:

• request.xyz (can be abbreviated by req.xyz)
• physical.xyz (can be abbreviated by phys.xyz)
• response.xyz (can be abbreviated by resp.xyz)

Condition operators