Angel Configuration

lighttpd2 consists of two main binaries: the angel (lighttpd2) and the worker (lighttpd2-worker). The main configuration is used by the worker, and this chapter describes the configuration for the angel.
A standard distribution should install a angel config in /etc/lighttpd2/angel.conf with reasonable defaults which should work for most basic setups.

Angel concept

You can start the worker without the angel, but the angel provides some useful features:

The angel itself usually runs as root (needed for example to bind to privileged ports), but will spawn the worker with dropped privileges (usually a user like www-data is used). The worker doesn’t do any privilege dropping itself.
The angel can open/create log files for the worker with root permissions
The angel supports a graceful restart of the worker for config reloading: a new instance is spawned, and if it started successfully (checking config, …) it will replace the old instance. The old instance will finish the remaining requests.
As the angel is responsible for creating the listening network sockets, it can keep them open all the time and no request is lost.
The angel also does a simple supervise: if the worker crashes the angel will respawn it.

Config items

The config syntax is very similar to the main configuration, although it has no action blocks, setup blocks, conditionals and scopes.

user

drops privileges for spawning the worker

user username;

username: username to drop privileges to for spawning the worker

This item can only be specified once; if it is not specified it won’t drop privileges at all, which is useful if the angel itself doesn’t run as root. It should go without saying that you should never run the worker as root.
The username is also used to find all groups the user is in.

Example

user "www-data";

group

drops privileges for spawning the worker

group groupname;

groupname: groupname to drop privileges to for spawning the worker

Specify the main group to drop privileges to; a process can have multiple groups, and the others are given by the groups the user specified by user is in.
The default is the main group of the user specified by user, or not dropping privileges at all.

Example

group "www-data";

binary

specifies path to worker binary

binary path;

path: path to the lighttpd2-worker binary

This item should only be needed if you didn’t install the binaries at all (for testing).

Example

binary "/home/source/lighttpd2/autobuild/src/main/lighttpd2-worker";

config

specifies path to main config file

config path;

path: path to the main config file

By default /etc/lighttpd2/lighttpd.conf is used.

Example

config "/etc/lighttpd2-test/lighttpd.conf";

luaconfig

specifies path to a lua config file

luaconfig path;

path: path to the lua config file

By default a normal config file is used; you must use either a normal config file or a lua config file.

Example

luaconfig "/etc/lighttpd2/lighttpd.lua";

modules_path

specifies path to directory containing modules for the worker

modules_path path;

path: path to the directory containing modules for the worker

This item should only be needed if you didn’t install the binaries at all (for testing). For autotool builds the “real” module binaries are in a .libs subdirectory.

Example

modules_path "/home/source/lighttpd2/autobuild/src/modules/.libs";

wrapper

prefix worker command with other commands

wrapper wrappers;

wrappers: path to a wrapper command and its arguments

This item appends all given strings to the command prefix list (which starts as empty list). Before spawning the worker the binary path to the worker and its arguments (config, module path) are appended.
Wrappers can be used to run the worker with valgrind, strace and similar.

Example

# in multiple lines
wrapper [ "/usr/bin/valgrind" ];
wrapper [ "--leak-check=full", "--show-reachable=yes" ]
wrapper [ "--leak-resolution=high" ];

# or as one
wrapper [ "/usr/bin/valgrind", "--leak-check=full", "--show-reachable=yes", "--leak-resolution=high" ];

env

add environment variables for the worker

env vars;

vars: list of environment variables to add for the worker to run with

Append the given list of environment variables (starts empty), which can be either strings of the form "var=xyz" or key-value pairs "var" => "xyz" (the keys must not contain any =).

Example

# helps debugging with valgrind:
env [ "G_SLICE=always-malloc", "G_DEBUG=gc-friendly,fatal_criticals" ];

copy_env

copies environment variables for the worker from current environment

copy_env varnames;

varnames: list of environment variable names to copy

Adds copies of variables from the current environment. By default all variables will be dropped.

Example

env_copy [ "PATH" ];

max_core_file_size

sets limit of core file size for the worker

max_core_file_size limit;

limit: limit in bytes

Maximum size of a core file, in bytes, that may be created by the worker. Core files are created when the worker crashes.
0 disables core files, and by default the limit is not changed.

max_open_files

sets limit of maximum open file for the worker

max_open_files limit;

limit: maximum number of open files

The worker limits the maximum number of connection based on the maximum number of open files (max connections = max open files / 4).
By default the limit is not changed.

Example

# max 4096 connections
max_open_files 16384;

allow_listen

allow worker to listen on sockets

allow_listen list;

list: list of network mask (CIDR) + optional port or unix domain socket addresses

The worker uses the angel to bind TCP/unix sockets; the angel checks whether those binds are allowed. If no allow_listen is specified, all TCP binds (IPv4 and IPv6) using port 80 or 443 are allowed.
IPv4 and IPv6 use different masks (no IPv4 to IPv6 mapping), the network length for the CIDR mask is optional (defaults to a host address), and the port is optional too (allowing both 80 and 443 if omitted).
Formats:

TCP on IPv4: ipv4, ipv4:port, ipv4/net, ipv4/net:port
TCP on IPv6: ipv6, ipv6/net, [ipv6], [ipv6/net], [ipv6]:port, [ipv6/net]:port
Unix domain: unix:/wildcard/path/to/*.socket

Example

Only allow TCP port 8080 for IPv4 and IPv6 and unix domain socket /run/lighttpd/internal.sock.

allow_listen [ "0.0.0.0/0:8080", "[::/0]:8080" ];
allow_listen "unix:/run/lighttpd/internal.sock";