Translation(s): none


Lighttpd is a web server aiming to be light, secure, and standards-compliant. Its configuration is simple, though it can be extremely powerful when needed through the use of additional modules. It has wonderful documentation, however this page will document basic Lighttpd configuration with Debian, which ships with some changes and sane defaults compared to upstream.


Installation

You can get a minimal instance of Lighttpd by simply installing the lighttpd package. Lighttpd 1.4.59 is available in Buster backports. Lighttpd 1.4.69 is available in Debian 12/Bookworm.

The base package is extremely small and only comes with a handful of core modules (most of which are also disabled by default), but additional modules are available in other packages:

At the very least, you likely want to install one of the modules for TLS support, as well as mod_deflate to substantially reduce the size of sent data. Both of these require additional configuration before they will work. See the mod_deflate page on the Lighttpd Wiki, and the SSL/TLS section on this page.


Configuration

By installing the base package, Debian will enable a minimal set of modules, install the systemd services for Lighttpd, bind to port 80, run as the www-data user, use /var/www/html as the webroot, serve over HTTP/2, and serve any files named "index.php" or "index.html", if one is present, when a directory is accessed over the web. It also creates a set of default MIME types with a Perl script located at /usr/share/lighttpd/create-mime.conf.pl

Lighttpd is secure by default. It will not serve the contents of files ending in ".php", ".pl", or ".fcgi" (preventing data leakage until you've configured PHP), it will not list the contents of directories if no index is present, and it blocks any attempts to escape your web root.

Everything can be tweaked in the /etc/lighttpd/lighttpd.conf file. You are recommended to go through it and make any desired changes.

Modules can be enabled by running the "lighty-enable-mod" command. This will show you a list of modules you have installed, along with displaying which are disabled and which are enabled. You can enable a module by entering its name into the prompt. "lighty-disable-mod" is also present, and works similarly. Changes will not take effect immediately, any changes to your configuration or to the active state of modules will require you to run systemctl reload lighttpd

Also note that some modules may not appear, even after installation, if they do not ship with a default configuration file. This includes, for instance, mod_redirect, which will require you to create a configuration file yourself.

Module configuration files are located in /etc/lighttpd/conf-available/ and will often require manual editing before functioning as expected, particularly if they may be a security risk. The usage of each module will not be documented on this page as it's version-dependent, and changes often. The Lighttpd Wiki documents almost every module thoroughly, including version-specific differences. You can add files to this directory, and they will appear in lighty-enable-mod

Enabling a module will symlink its configuration file from /etc/lighttpd/conf-available/ to /etc/lighttpd/conf-enabled/ where Lighttpd is instructed to load configuration files from. The number at the start of the filename indicates load order. The lower the number, the sooner it's loaded.

You can test a configuration file by running the lighttpd command in combination with the -tt flag, as well as a -f flag that points to your configuration file. For example:

# lighttpd -tt -f /etc/lighttpd/lighttpd.conf

This will validate your Lighttpd configuration, including that of any modules you've enabled. It will also inform you of any errors that would prevent Lighttpd from starting, as well as list any warnings.


PHP

There are two solutions for using PHP with Lighttpd. The older solution is with PHP-CGI, the newer (and faster!) solution is using PHP-FPM, however PHP-FPM requires using Lighttpd from Debian 11, or Debian 10's backports.

Configuration is fairly simple either way. Install php-cgi or php-fpm depending on which method you chose. Then run either lighty-enable-mod fastcgi-php (For PHP-CGI) or lighty-enable-mod fastcgi-php-fpm (For PHP-FPM), and then reload your Lighttpd configuration with systemctl reload lighttpd for it to take effect. It should now be properly handling PHP files.

To verify this, you can create a folder in your webroot named, e.g., "info.php", with these contents:

<?php
phpinfo();
?>

and then access this file from your browser. It should display a large amount of relevant information, if all is working well. Note that you may wish to remove this file after you have verified that it's working properly, as it dumps a large amount of information that could potentially be useful to an attacker.

You should take note of the "Loaded Configuration File" line though, as this will direct you to the relevant PHP configuration file that you should edit. This is dependent on both the server API you're using to connect PHP, as well as your PHP version.

In some cases, you may need to set "cgi.fix_pathinfo = 1" in your php.ini file. However, this should already be the default in recent versions of PHP. If you have disabled this option for some other application, you will need to re-enable it for Lighttpd.

If using PHP-CGI, you may be interested in this guide on tuning it for performance: https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_PerformanceFastCGI


SSL/TLS (HTTPS)

Today, SSL/TLS is strongly recommended in all cases. Among privacy and security benefits, it is required for HTTP/2 to work, meaning it may meaningfully improve your site's load times as well.

Typically, the best and easiest way to obtain a certificate for a public-facing website is through Let's Encrypt (Certbot). Unfortunately, though Certbot has automated plugins for Apache2 and Nginx, it does not have one for Lighttpd, making this process more manual than it would be otherwise.

This topic is also covered on https://redmine.lighttpd.net/projects/1/wiki/HowToSimpleSSL and https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL, however this article will contain a quick-start. You should read the full SSL documentation at some point, however.

Install the certbot package. Then, request a certificate by running:

certbot certonly --manual --preferred-challenges dns

and following the on-screen prompts. You will need access to your domain's DNS to add TXT records. After it is confirmed, it should create a usable SSL certificate for you in the /etc/letsencrypt/live/your.domain/ folder, replacing "your.domain" with the primary domain you requested a certificate for. If the certificate files are placed somewhere else, take note of this, as you will need to refer to them later.

Next, you'll need to set up your configuration with Lighttpd. This will, again, be an oversimplified solution to get you started quickly. Open your /etc/lighttpd/conf-available/10-ssl.conf file and erase its default contents. Go to https://ssl-config.mozilla.org/ in your browser and select "lighttpd" for your server software. Fill in other details, such as your Lighttpd version and your OpenSSL version. You are also recommended to choose which clients you wish to support, with the buttons under the "Mozilla Configuration" header.

As you do this, it will generate contents for your configuration file in a box below. There is a button labeled "Copy" in the bottom-right of this textbox that will copy its contents to your clipboard. You should paste this into the configuration file that you previously wiped.

You will still need to make minor changes. At the top of the file, it contains several commented lines that load required modules, likely including mod_redirect, mod_setenv, and mod_openssl. If these have not already been enabled elsewhere, you should uncomment them by removing the # symbol at the start of the line.

Then, you will need to fill out the "ssl.privkey" and "ssl.pemfile" lines with the files you were given by Certbot. This will likely look like:

ssl.pemfile = "/etc/letsencrypt/live/your.domain/fullchain.pem" 
ssl.privkey = "/etc/letsencrypt/live/your.domain/privkey.pem" 

again, replacing your.domain with the real name of the folder (most likely the primary domain of the certificate), or adjusting the entire path if Certbot placed them in a different folder.

This should be enough. Load the module with lighty-enable-mod ssl and reload your configuration with systemctl reload lighttpd for it all to take effect. Assuming you have an A record in your domain's DNS correctly pointing to your server's IP address, and ports 80 and 443 are properly forwarded and aren't otherwise blocked, then users should be able to go to your domain and see your website, with full encryption.

If you've made a mistake, your website may now be inaccessible, even if it was working previously. If so, disable the SSL module and reload the site's config again, so you can buy yourself time to investigate the problem. Good luck!


Performance

Lighttpd is, at least out-of-the-box, a "single-threaded, single-process, event-based, non-blocking-IO web server". There aren't many "performance knobs" to tweak with Lighttpd, as opposed to other web servers. More often, performance issues will be on your backend. Before diving into this, make sure that Lighttpd itself is your issue, and not the processes it's handing data off to.

To the extent that you can improve things through tweaking (both of Lighttpd itself and of your host system), this is documented well on the Lighttpd wiki: https://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_Performance

In some cases, if Lighttpd is bottlenecked by your CPU or I/O read speed, you may consider adding additional workers, meaning that it will start additional Lighttpd processes to listen on the same socket, effectively making use of multiple CPU cores and enabling Lighttpd to process requests highly concurrently. This does come with limitations however. Please see the official documentation at https://redmine.lighttpd.net/projects/lighttpd/wiki/Server_max-workerDetails for more details.


Troubleshooting

If you get an error when you restart or reload Lighttpd, you may need to check the journal to see its log in detail. You can view the last hundred lines by running:

# journalctl -u lighttpd.service -n 100

Use your arrow keys, along with PgUp and PgDn to scroll through. Look at the most recent lines. Try to find any meaningful output describing the problem. Lighttpd is good at giving intelligible errors, you can often diagnose and fix the problem yourself with minimal effort.


See also


CategoryNetwork CategorySoftware