Setting up the lightweight Lighttpd web server

Fast Delivery

Supplying the Configuration

As an experiment, save your lighttpd.conf file if it already exists, and then create a new configuration file with the contents from Listing 1. Type

lighttpd -t -f /etc/lighttpd/lighttpd.conf

to first check for syntax errors (Figure 1). A typo like server.prot=80 would not be detected. You should therefore still check the error log after reloading the configuration. Figure 2 shows a configuration test with the parameter -D, which outputs messages to the terminal.

Figure 1: The -t parameter tells Lighttpd to check syntax.
Figure 2: The -D switch keeps Lighttpd in the foreground and outputs messages to the terminal, which would be useful for a quick test of a new configuration.

The new settings are applied by the web server as soon as it receives the SIGUSR1 signal. If you have a distribution that uses systemd, use:

sudo systemctl reload lighttpd.service

Otherwise the manual approach is to run

sudo kill -n SIGUSR1 <PID>

To discover the <PID>, run:

ps -A | grep lighttpd

Table 1 lists the signals that Lighttpd understands. If the web server is not yet running, typing either of the lines,

sudo systemctl start lighttpd.service
sudo lighttpd -f /etc/lighttpd/lighttpd.conf

will enable it at once.

Table 1

Signals Supported by Lighttpd

Signal Response
SIGTERM Terminates Lighttpd immediately; existing connections are interrupted
SIGINT Lighttpd responds to all current requests and then terminates
SIGUSR1 Lighttpd responds to all current requests and then reloads its configuration
SIGHUP Lighttpd reopens its logfiles but does not reload the configuration

Flexible Condition

Imagine you want Lighttpd always to return pages from /var/www/html/blog when a browser requests the blog from You can manage this in the configuration file with conditionals. The lines

$HTTP["host"] == "" {
  server.document-root = var.dir + "/html/blog"

test whether the requested hostname is identical to

The $HTTP["host"] element stands for the requested host name; all data available as an alternative is summarized in Table 2. If the condition is true, Lighttpd evaluates all the settings in the brackets. The example defines /var/www/html/blog/ as the document root folder. All settings between the curly braces thus only apply to In this way, completely different configurations can be stored for different domains and, in turn, virtual hosts can be implemented.

Table 2

Data in Conditionals

Field Meaning
$REQUEST_HEADER["..."] The information specified in the quotes from the request header (e.g., $REQUEST_HEADER["User-Agent"] refers to the user agent)
$HTTP["request-method"] Request method
$HTTP["scheme"] Schema of incoming connection, either http or https
$HTTP["host"] Hostname
$HTTP["url"] Complete URL path without the domain name and query strings
$HTTP["querystring"] Query string (everything after the ? in the URL)
$HTTP["remoteip"] Remote IP or remote network; only works with IPv4
$SERVER["socket"] Socket; only works with the == operator; additionally, the value must have the format <IP>:<Port>.

Instead of ==, a != tests for inequality. Additionally, more complex rules can be formulated with regular expressions. Lighttpd evaluates settings in the curly brackets if the regular expression to the right of =~ is true or the expression to the right of !~ is false. For example,

$HTTP["url"] =~ "^/blog/"

would check to see whether the URL requested by the browser starts with /blog/. Lighttpd also supports conditionals. Consequently, a conditional can contain other conditions between the curly braces.

Communication Secret

Most of Lighttpd's functions are provided by modules that can be activated as needed. Encrypted connections over TLS are provided by the mod_openssl module,

server.modules = ("mod_openssl")
$SERVER["socket"] == ":443" {
  ssl.engine = "enable"
  ssl.pemfile = "/etc/lighttpd/server.pem"

which in turn relies on OpenSSL. In Lighttpd 1.4.56, four more modules joined the mix, handling encryption with mbed TLS (mod_mbedtls), wolfSSL (mod_wolfssl), GnuTLS (mod_gnutls), and NSS (mod_nss). However, they are still considered experimental.

To use the SSL module, you must first load it in lighttpd.conf:

server.modules = ( "mod_openssl" )

The settings for the module end up back in the central configuration file. In the case of mod_openssl, the mod_openssl module lines shown previously are all you need: The conditional checks whether the request has come in through port 443. In this case, ssl.engine enables encryption with the certificate specified by ssl.pemfile.

You can generate a suitable self-signed certificate with OpenSSL:

$ openssl req -new -x509 -keyout /etc/lighttpd/server.pem -out /etc/lighttpd/server.pem-days 365 -nodes

Lighttpd also supports the Let's Encrypt project. The somewhat more complex configuration required for this is explained in detail on a wiki page [4].

Buy this article as PDF

Express-Checkout as PDF
Price $2.95
(incl. VAT)

Buy ADMIN Magazine

Get it on Google Play

US / Canada

Get it on Google Play

UK / Australia

Related content

comments powered by Disqus
Subscribe to our ADMIN Newsletters
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.