Linode Library Home
Linode Library RSS Feed
Home :: Web Servers :: Lighttpd
Print View View Source

lighttpd Web Server on Ubuntu 9.10 (Karmic)

Published: by

Warning

This document is an older, unmaintained guide. There may be a new guide available for this software.

This tutorial explains how to install and configure the lighttpd (eg. "lighty") web server on Ubuntu 9.10 (Karmic). Lighttpd is designed to provide a lightweight web server that is capable of serving large loads and using less memory than servers like the Apache HTTP server. It's commonly deployed on high traffic sites, including YouTube. You might want to consider using lighttpd if you're having problems scaling your current web server to meet your load requirements. Lighttpd makes sense for users who find "big" programs like Apache daunting and bloated.

Our example will illustrate the installation of a lighttpd server on an Ubuntu 9.10 (Karmic) system. We assume that you've followed the getting started guide and are running on an updated system. This document does not, however, include instructions for deploying other common services in the web development stack. We recommend you consult additional resources (a few are listed at the end of this tutorial) to deploy the remainder of your web stack.

If you're switching from an alternate web server like Apache, remember to turn Apache off for testing purposes, or configure lighttpd to serve on an alternate port until it's configured properly.

For purposes of this tutorial we'll assume you are logged into an SSH session on your Linode as the root user.

Contents

Set the Hostname

Before you begin installing and configuring the components described in this guide, please make sure you've followed our instructions for setting your hostname. Issue the following commands to make sure it is set properly:

hostname
hostname -f

The first command should show your short hostname, and the second should show your fully qualified domain name (FQDN).

Installing lighthttpd

Edit your /etc/apt/sources.list file to enable the "universe" repositories by removing the hash symbol in front of the universe lines. The file should resemble the following example:

File:/etc/apt/sources.list

## main & restricted repositories
deb http://us.archive.ubuntu.com/ubuntu/ karmic main restricted
deb-src http://us.archive.ubuntu.com/ubuntu/ karmic main restricted

deb http://security.ubuntu.com/ubuntu karmic-security main restricted
deb-src http://security.ubuntu.com/ubuntu karmic-security main restricted

## universe repositories
deb http://us.archive.ubuntu.com/ubuntu/ karmic universe
deb-src http://us.archive.ubuntu.com/ubuntu/ karmic universe

deb http://us.archive.ubuntu.com/ubuntu/ karmic-updates universe
deb-src http://us.archive.ubuntu.com/ubuntu/ karmic-updates universe

deb http://security.ubuntu.com/ubuntu karmic-security universe
deb-src http://security.ubuntu.com/ubuntu karmic-security universe

When you have saved this file, issue the following commands to refresh your system's package database and ensure that you're running the most up to date software:

apt-get update
apt-get upgrade --show-upgraded

First, install the server using apt-get by issuing the following command:

apt-get install lighttpd

Once the server is installed we'll want to check to make sure that it's running and is enabled. Visit http://[your-ip-address]:80 in your browser. If you have set up lighttpd to run on an alternate port for testing, be sure to replace 80 with this port. You'll see a placeholder page for lighttpd that contains some important information. Notably:

Configuring Lighttpd

You will want to configure your lighttpd instance to provide only the services that you need for your use case. Strictly speaking none of the configuration options described in this section are required for any or all setups. Nevertheless, many of these options may prove useful in your configuration process.

We've also provided an example configuration, with extensive comments, which might help contextualize this reference and the configuration process.

Begin by entering the command lighty-enable-mod at the command prompt. You will be provided with a list of available modules and a list of already enabled modules, as well as a prompt to enable a module. You can exit with Control-c, or you can enable one of the modules at this point. You may also use lighty-enable to activate this prompt.

For a basic compliment of modules we might begin by enabling SSI (for server side includes) and auth modules with the following command:

lighty-enable-mod ssi auth

You may also want to enable the mod_rewrite (rewriting URL requests) and mod_evhost (virtual hosting of domains and subdomains) modules, which you can do by uncommenting the appropriate lines at the beginning of the config file (/etc/lighttpd/lighttpd.conf). Some highlights of this file allow you to:

When you've completed your configuration you must reload the configuration with the following command:

/etc/init.d/lighttpd force-reload

There are many additional modules that are included in separate Ubuntu packages. They can be installed with apt-get install and the salient ones are:

When you have installed these packages you will be able to enable them using the lighty-enable-mod interface. For more information regarding installation and configuration of specific modules, consult the lighttpd documentation.

Remember to reload lighttpd after you've finished installing, enabling, and configuring new modules.

Virtual Host Setup with Simple Vhost

Configure Simple Vhost Module

Ensure that all other virtual hosting modules are turned off.

This section covers configuration for simple virtual hosting. The mod_simple_virtual hosts allows you to quickly set up virtual hosts with respective DocumentRoots in folders named for the domains, below a "server root."

Begin by enabling mod_simple-vhost with the following command:

lighty-enable-mod simple-vhost

and continue by reloading lighttpd:

/etc/init.d/lighttpd force-reload

Modify the following settings in your /etc/lighttpd/conf-enabled/10-simple-vhost.conf file:

File excerpt:/etc/lighttpd/conf-enabled/10-simple-vhost.conf

simple-vhost.server-root = "/srv/www"
simple-vhost.document-root = "/public/"
# simple-vhost.default-host = "brackley.org"

After editing this file reload the web server again with the following command:

/etc/init.d/lighttpd force-reload

The server-root defines the base directory under which all virtual host directories are created.

The default-host specifies which host name will be directed to the default site. For optimum operation, you should not set this value.

The document-root defines the subdirectory under the default-host directory that contains the pages to be served. This is comparable to the public_html/ directory you may be familiar with from some Apache configurations, and is called public/ in the above configuration.

In this configuration, lighttpd will look for directories in /srv/www/ that correspond to domain and subdomain requests and serve results from those directories. If lighttpd receives a request and cannot find a directory it serves content from the default-host directory.

Create Simple Virtual Hosts

Once the required simple-vhost. directives are instantiated as above, create the required directories to create the default virtual host:

mkdir -p /srv/www/example.com/public/

Issue the following commands to create two additional virtual hosts:

mkdir -p /srv/www/example.net/public/
mkdir -p /srv/example.org/public/

Use the following sequence of commands to create default index pages for all sites:

echo "<h1>Welcome to example.com</h1> <p>It is the default site</p>" > /srv/www/example.com/public/index.htm
echo "<h1>Welcome to example.net</h1>" > /srv/www/example.net/public/index.htm
echo "<h1>Welcome to example.org</h1>" > /srv/www/example.org/public/index.htm

Virtual Host Setup with Enhanced Vhost

Remove the hash (#) from the front of the the line that reads "mod_evhost" in the server.modules block of the /etc/lighttpd/lighttpd.conf file.

Now, let's examine the following section of the default config file:

File excerpt:lighttpd.conf

# define a pattern for the host url finding
# %% => % sign
# %0 => domain name + tld
# %1 => tld
# %2 => domain name without tld
# %3 => subdomain 1 name
# %4 => subdomain 2 name
#
# evhost.path-pattern = "/home/storage/dev/www/%3/htdocs/"

To accomplish the same directory structure with evhost as with the simple-vhost, we would need to insert the following statement into lighttpd.conf:

File excerpt:lighttpd.conf

evhost.path-pattern = "/srv/www/%0/public/"

You have maximum flexibility to create virtual hosts in this manner. The naming convention for these virtual hosts is derived from the domains names, given the following (ficticious) web address: http://lookhere.somesubdomain.example.com/

We read domain names backwards, so com is the tld or "top level domain", example is the domain, somesubdomain is the subdomain 1 name, and lookhere is the subdomain 2 name. These can be combined using the above syntax to create a virtual hosting scheme that makes sense for your use case.

Virtual Hosting Best Practices

The way you set up virtual hosting on your web server is highly dependent upon what kind of sites you need to host, their traffic, the number of domains, and the workflows associated with these domains. We recommend hosting all of your domains in a centralized top level directory (eg. /var/www/ or /srv/www) and then symbolically linking these directories into more useful locations.

For instance, you can create a series of "web editor" user accounts. You may then link the "DocumentRoot" of each domain into a folder in the home folder of the account of the editor for that domain. For the user account "abraham-brown" that manages the "brackley.com" site, the link would be created like so:

ln -s /home/myuser/example.com/ /srv/www/example.com

You can also use symbolic links to cause multiple virtually hosted domains to host the same files. For example, to get example.org to point to example.com's files, create the following link:

ln -s /srv/www/example.org/ /srv/www/example.com

No matter what you decide, we recommend developing some sort of systematic method for organizing virtual hosting so that you don't becomes confused down the road when you need to modify your system.

Running Scripts with mod_fastcgi

If you need your web server to execute dynamic content, the preferred way to accomplish this with lighttpd is to run these scripts using FastCGI. To run a script, FastCGI externalizes the interpreter for the script for dynamic web applications from the web server rather than running the scripts "inside" the web server. This is in contrast to the common Apache-based approaches such as mod_perl, mod_python, and mod_php. If you're familar with Apache this might seem foreign and/or antiquated, but in high-traffic situations doing things this way is often more efficient and effective.

To set up FastCGI you need to make sure that an interpreter is installed on your system that is capable of running your scripts. Perl version 5.10.0-19 is included in Ubuntu by default. Issue one of the following commands:

# to install python
    apt-get install python

# to install ruby
    apt-get install ruby

# to install PHP version 5 for CGI interfaces
    apt-get install php-cgi

You will almost certainly need to install and set up a database system of some sort as well, depending on the software you intend to run.

Lighttpd will send CGI requests to CGI handlers on the basis of file extensions, and every file extension can be forwarded individual handlers. You may also forward requests for one extension to multiple servers, and Lighttpd will automatically load balance these FastCGI connections.

If you install the php5-cgi package and enable mod_fastcgi with lighty-enable-mod fastcgi then a default FastCGI handler will be configured in the file /etc/lighttpd/conf-enabled/10-fastcgi.conf. Though the handler will likely require specific customization for your use cases, it serves as an effective example:

File excerpt:/etc/lighttpd/conf-enabled/10-fastcgi.conf

fastcgi.server    = ( ".php" =>
        ((
                "bin-path" => "/usr/bin/php-cgi",
                "socket" => "/tmp/php.socket",
        "max-procs" => 2,
                "idle-timeout" => 20,
                "bin-environment" => (
                        "PHP_FCGI_CHILDREN" => "4",
                        "PHP_FCGI_MAX_REQUESTS" => "10000"
                ),
                "bin-copy-environment" => (
                        "PATH", "SHELL", "USER"
                ),
                "broken-scriptfilename" => "enable"
        ))
)

You can map more than one file extensions to a single FastCGI handler by adding the following entry to your config file:

File excerpt:/etc/lighttpd/conf-enabled/10-fastcgi.conf

fastcgi.map-extensions = ( ".[ALT-EXTENSION]" => ".[EXTENSION]" )

Again, mod_fastcgi supports creating multiple handlers, and even adding multiple FastCGI back ends per-handler.

Lighttpd Caveats

While lighttpd is an effective and capable web server there are two caveats regarding its behavior that you should be familiar with as you continue on your lighttpd path.

First, server side includes, which allow you to dynamically include content from one file into another do not function in lighttpd in the same way that they function in Apache's mod_ssi. While it is an effective method for quickly assembling content, lighttpd's script handling via SSI is not a recommended work flow. See lighttpd project documentation on mod_ssi

Secondly, because of the way FastCGI works, running web applications with lighttpd requires additional configuration, particularly for users who are writing applications using interpreters embedded in the web server (eg. mod_perl, mod_python, mod_php, etc.). This is especially true for effective optimizations.

Additional Ubuntu Configuration

The default configuration for Ubuntu (in addition to /etc/lighttpd/lighttpd.conf) automatically includes all of the files in the /etc/lighttpd/conf-enabled/ directory with the .conf extension. Typically, these files are symbolically linked from the /etc/lighttpd/conf-available/ directory by the lighttpd-enable-mod. You can add specific configuration directives for required modules in these files, or in the master lighttpd.conf file, depending on your needs and personal preference.

Example Configuration

Lighttpd is often deployed in specialized high performance environments, with configurations for specific use cases. This makes it difficult to recommend a prototypical configuration for lighttpd. Nevertheless, we offer this well-commented example as a guide to developing your own lighttpd configuration.

Example lighttpd Configuration with Comments

Please note that comments in this file reference Debian, however this file will work on Ubuntu deployments as well.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

Creative Commons License

This guide is licensed under a Creative Commons Attribution-NoDerivs 3.0 United States License.

Last edited by Sharon Campbell on Monday, October 7th, 2013 (r3834).