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.
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-datais 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.
The config syntax is very similar to the main configuration, although it has no action blocks, setup blocks, conditionals and scopes.
drops privileges for spawning the worker
- 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.
drops privileges for spawning the worker
- 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.
specifies path to worker binary
- path to the @lighttpd2-worker@ binary
This item should only be needed if you didn’t install the binaries at all (for testing).
specifies path to main config file
- path to the main config file
/etc/lighttpd2/lighttpd.conf is used.
specifies path to a lua config file
- 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.
specifies path to directory containing modules for the worker
- 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
prefix worker command with other commands
- path to a wrapper command and its arguments
This item appends all given strings to the comannd 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.
# 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" ];
add environment variables for the worker
- 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
# helps debugging with valgrind: env [ "G_SLICE=always-malloc", "G_DEBUG=gc-friendly,fatal_criticals" ];
copies environment variables for the worker from current environment
- list of environment variable names to copy
Adds copies of variables from the current environment. By default all variables will be dropped.
env_copy [ "PATH" ];
sets limit of core file size for the worker
- 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.
sets limit of maximum open file for the worker
- 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.
# max 4096 connections max_open_files 16384;
allow worker to listen on sockets
- 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).
TCP on IPv4:
TCP on IPv6:
- Unix domain:
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";