A [closer] look at lighttpd.conf & its constituents

In the last guide, I showed you how to install the lighttpd web server,

in this post, I will discuss the lighttpd.conf located at /etc/lighttpd/lighttpd.conf & the various configurations available.



  • Continued configuration
  • Configuration overview
  • Name based virtual hosting
  • Error handlers

Continued configuration 

This explains what to do after the previous post.


If you have recently installed the lighttpd web server, point your browser to your domain.

If all is well, you should see this placeholder page (named index.lighttpd.html).

To edit the directory, and/or index page,

navigate to your server document root (as defined by lighttpd.conf - explained here)



Configuration overview

This is a brief overview of the directives in your config file.



This is a shorten list of the configuration options, a full list is available here.



server.document-root: The top level document root

server.port: The server port, default 80.

server.upload-dirs: The upload directory

server.max-connections: How many concurrent connections supported by the server. 1/2 recommended.

server.max-fds: Max file descriptors - set higher than max-connections (max-connections == max-fds/2)

server.max-keep-alive-idle: Maximum seconds before a idling keep-alive connection is dropped

connection.kbytes-per-second: Maximum kilobytes that a connection is limited to

server.kbytes-per-second: Limits the maximum kilobytes for the entire server. (kbyte/s)

server.max-request-size: Maximum size (kbyte) of request



mod_access: Access restrictions

mod_alias: Directory aliases

mod_compress: Reduces network load

mod_redirect: Redirects set of URLS


Let's take a look at the server document root, given by the core directive:

server.document-root =

This specifies where the top level document root is located, you can change it to specify where the default directory is.

(For example:  server.document-root = "/home/lighttpd/public_html/")

In order to have a fully running web server, you must specify the correct directory.


Name based virtual hosting

This enabled you to host multiple websites from a single IP address.


This example shall create 'website1' and 'website2'.


  • Firstly, you must have the required directories for the websites you want to host.


To do this:


# mkdir -p /home/lighttpd/default/http/

This is going to be our default 'main' document root.


# mkdir -p /home/lighttpd/website1.com/http
# mkdir -p /home/lighttpd/website1.com/logs
# mkdir -p /home/lighttpd/website2.com/http
# mkdir -p /home/lighttpd/website2.com/logs

These are our default document root & logs for website1 & website2.


  • Next, we will edit the lighttpd.conf file:
# vi /etc/lighttpd/lighttpd.conf


Change the default document root & point it to our defined document root:

server.document-root = "/home/lighttpd/default/http/"


Add the following lines:

include "website1.com.conf"
include "website2.com.conf"


Save and exit (:wq).


  • Creating website virtual host configuration:


Edit website configuration:


# vi /etc/lighttpd/website1.com.conf


Add the following lines:

$HTTP["host"] =~ "website1\.com" {
              server.document-root = "/home/lighttpd/website1.com/http"
              accesslog.filename = "/home/lighttpd/website1.com/logs/access.log"

(Simply replace the underlined with your website domain/directory)

Save and close (:wq)


Repeat this process for website2;


# vi /etc/lighttpd/website2.com.conf


Add the following lines:


$HTTP["host"] =~ "website2\.com" {
              server.document-root = "/home/lighttpd/website2.com/http"
              accesslog.filename = "/home/lighttpd/website2.com/logs/access.log"


Save and quit.


  • Force reload lighttpd:
/etc/init.d/lighttpd force-reload




Error Handlers

This will detail how to customize your 404 status page using lighttpd web server.


  • Edit your lighttpd.conf:


# vi /etc/lighttpd/lighttpd.conf

  • Add the line:


server.error-handler-404 = "/error-404.php"

This calls upon the file 'error-404.php' located in the website's document root whenever a 404 error has been returned.


  • Save and exit - you're done!



Leave a Reply