Configuration¶

How much time do you have to set up lighttpd? 5 minutes? 10 minutes? More?

5 minutes¶

Want to run a fast, low-resource server for static content? It's easy. Create a text file named lighttpd.conf with the following content:

server.document-root = "/var/www/servers/www.example.org/pages/" 

server.port = 3000

# If running lighttpd earlier than lighttpd 1.4.71, uncomment (remove '#') to add the following:
#mimetype.assign = (
#  ".html" => "text/html", 
#  ".txt" => "text/plain",
#  ".jpg" => "image/jpeg",
#  ".png" => "image/png" 
#)

lighttpd will bind to all interfaces by default and will listen for HTTP requests on the port specified in server.port (default is port 80). lighttpd will then serve files from the server.document-root specified. The files in the document root -- the base directory that is used for all requests -- have to be readable by the user starting the web server. For lighttpd earlier than lighttpd 1.4.71, uncomment mimetype.assign to assign a few important MIME types.

First, check that your configuration is ok:

$ lighttpd -tt -f lighttpd.conf

Now start the server for testing:

$ lighttpd -D -f lighttpd.conf

and point your browser (running on same machine as lighttpd) to http://127.0.0.1:3000/index.html

To stop the server and return to the command prompt, press Ctrl-C.

A real daemon¶

Next you should familiarize yourself with some settings necessary for your server's security:

server.document-root = "/var/www/servers/www.example.org/pages/" 

#server.port = 80   # 80 is the default listening port number, if not otherwise specified

server.username = "www" 
server.groupname = "www" 

# If running lighttpd earlier than lighttpd 1.4.71, uncomment (remove '#') to add the following:
#mimetype.assign = (
#  ".html" => "text/html", 
#  ".txt" => "text/plain",
#  ".jpg" => "image/jpeg",
#  ".png" => "image/png" 
#)

static-file.exclude-extensions = ( ".fcgi", ".php", ".rb", "~", ".inc" )
index-file.names = ( "index.html" )

Now the web server is listening on port 80, the default for HTTP traffic, and will switch to the user www and the group www.
The server has to be started as root to take control of port 80, but it's not necessary or a good idea to continue running as root after port acquisition, so the server switches to user www.

Lastly, access to view the contents of some types of files is forbidden as they are used for generating dynamic content. Requests directly to a directory are rewritten to the index.html file in that directory.

Assuming you have already created the /etc/init.d/lighttpd service as described in "Init Script" section of InstallFromSource, place the config file in /etc/lighttpd/lighttpd.conf and start the server with:
# /etc/init.d/lighttpd start
To stop it use:
# /etc/init.d/lighttpd stop

For systemd-based distributions:
systemctl start lighttpd
and
systemctl stop lighttpd

10 minutes¶

Conditionals, conditionals, conditionals:

A powerful feature of the lighttpd configuration is the use of conditionals. Using simple or regular expression conditions, default setting can be overridden.

server.document-root = "/var/www/servers/www.example.org/pages/" 

#server.port = 80   # 80 is the default listening port number, if not otherwise specified

server.username = "www" 
server.groupname = "www" 

# If running lighttpd earlier than lighttpd 1.4.71, uncomment (remove '#') to add the following:
#mimetype.assign = (
#  ".html" => "text/html", 
#  ".txt" => "text/plain",
#  ".jpg" => "image/jpeg",
#  ".png" => "image/png" 
#)

static-file.exclude-extensions = ( ".fcgi", ".php", ".rb", "~", ".inc" )
index-file.names = ( "index.html" )

$HTTP["host"] == "www2.example.org" {
  server.document-root = "/var/www/servers/www2.example.org/pages/" 
}

Now we have a new virtual server, www2.example.org, which uses the same settings as the first server, only the document root is different.

The following server configuration adds a download area and enables the built-in directory listing feature:

server.document-root = "/var/www/servers/www.example.org/pages/" 

#server.port = 80   # 80 is the default listening port number, if not otherwise specified

server.username = "www" 
server.groupname = "www" 

# If running lighttpd earlier than lighttpd 1.4.71, uncomment (remove '#') to add the following:
#mimetype.assign = (
#  ".html" => "text/html", 
#  ".txt" => "text/plain",
#  ".jpg" => "image/jpeg",
#  ".png" => "image/png" 
#)

static-file.exclude-extensions = ( ".fcgi", ".php", ".rb", "~", ".inc" )
index-file.names = ( "index.html" )

$HTTP["host"] == "www2.example.org" {
  server.document-root = "/var/www/servers/www2.example.org/pages/" 
  $HTTP["url"] =~ "^/download/" {
    dir-listing.activate = "enable" 
  }
}

As you can see, conditionals can be nested: only the download folder and its sub-folders have the directory listings enabled.

There's also the else clause for conditionals. Despite the name, it's an else if construct similar to some programming languages, as it has to be followed by another condition.

Here's an example of conditional-based vhosts. The else is being used to configure behavior that should be present only in "default" vhost.

$HTTP["host"] == "example.org" {                                                                                         
  # options specific to example.org
  expire.url = ( "" => "access plus 25 hours" )                                                                                        
} else $HTTP["host"] == "static.example.org" {
  # options specific to static.example.org
  expire.url = ( "" => "access plus 2 weeks" )                                                                                        
} else $HTTP["host"] =~ "" {                                                                                                           
  # options applied to any other vhosts present on this ip 
  # ie. default options
  expire.url = ( "" => "access plus 3 hours" )                                                                                        
} 

Now that we've covered the basics, you're ready to learn some more advanced topics like includes and configuring PHP with FastCGI

After 30 minutes¶

Now you know the basic set up, include files, and maybe even how to set up PHP or Ruby. But there's so much more to find out.

Most of it is described in examples in the default configuration file that you can also find in the doc directory of the tarball.

For the configuration file syntax and the complete list of configuration options, visit the configuration section of the wiki: Documentation

Also check out our community.