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.

Flexible Condition

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

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

test whether the requested hostname is identical to blog.example.com.

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 blog.example.org. In this way, completely different configurations can be stored for different domains and, in turn, virtual hosts can be implemented.

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].