Gentoo Wiki



Base Install

  1. What is Gentoo?
  2. About
  3. Preparation
  4. Partitioning
  5. Configuring
  6. Stage Progression
  7. Kernel
  8. Bootloader
  9. Test
  10. Converting from or to a non-Gentoo distribution
  11. Troubleshooting
  12. Maintaining


Base Extras



Other Articles

This article will help you to setup LightTPD. LightTPD (pronounced "lighty") is a web server which is designed to be secure, fast, standards-compliant, and flexible while being optimized for speed-critical environments. It supports the FastCGI, SCGI and CGI interfaces to external programs, permitting web applications written in any programming language to be used with this server. As a particularly popular language, PHP performance has received special attention. Lighttpd's FastCGI can be configured to support PHP with opcode caches (like APC) properly and efficiently. Additionally, it has received attention from its popularity within the Ruby on Rails and Lua communities.




In this section, we will set USE flags and emerge the required package(s).

USE flags

Note: If you have gentoolkit installed, you can use the command 'euse' to handle USE flags. See 'man euse' for more information or the Euse wiki page. There are also other programs to help users manage USE flags, such as profuse.

The possible USE flags for LightTPD are:

Code: Using euse to display USE information
% euse --info bzip2
Code: Using euse to add USE flags to /etc/make.conf
% euse -E bzip2

Choose the USE flags you want to use, and add them to your /etc/make.conf. If you don't want to make all of these USE flags in your system, just for LightTPD you can use /etc/portage/package.use. To add your USE flag to your /etc/portage/package.use, this might help:

Code: Add your USE flags to /etc/portage/package.use
% echo "www-servers/lighttpd <your useflag selection here with space separation>" >> /etc/portage/package.use

Emerging LightTPD

Code: Emerging LightTPD
 # emerge -av lighttpd


Base Configuration

Fire up your editor to /etc/lighttpd/lighttpd.conf and lets get started editing. We won't cover more advanced things such as FastCGI, mod_simple_vhost, mod_cml, etc. Go though the configuration file and edit anything that you feel you need to edit.

PHP support

PHP support needs to be activated manually.

Check for FastCGI support

Your USE flags for FastCGI should include php and fastcgi. To check for FastCGI support, run php-cgi -v and look for "cgi-fcgi" in the version output. If you don't see this, try emerging PHP again after setting the USE flag cgi for the package dev-lang/php: emerge -av dev-lang/php.

See PHP for further information on how to set up PHP.

Enable FastCGI support

Open up your /etc/lighttpd/lighttpd.conf file with your favorite editor, and uncomment the line that looks like this:

Code: Line to uncomment
 #include "mod_fastcgi.conf"

Then, open up your /etc/lighttpd/mod_fastcgi.conf file, and uncomment the large block of code. In general it is already pre-configured so that you can move on with testing your setup. If needed, you can also modify the "bin-path" according to your PHP installation:

File: /etc/lighttpd/mod_fastcgi.conf
  "bin-path" => "/usr/bin/php-cgi"

You should enable cgi.fix_pathinfo in your php.ini. This makes your PATH_INFO and PHP_SELF variables usable with LightTPD otherwise many scripts will not work properly for you.

File: /etc/php/cgi-php5/php.ini
  cgi.fix_pathinfo = 1


File: /etc/lighttpd/lighttpd.conf
simple-vhost.server-root         = "/full/path/to/server/root"
simple-vhost.default-host        = "FQDN"
simple-vhost.document-root       = "/"
$HTTP["host"] =~ "^(www.)?FQDN" { server.document-root = "/full/path/to/server/root" }

user directories

Add mod_userdir to the list of modules to load.

File: /etc/lighttpd/lighttpd.conf
userdir.path = "public_html"
userdir.exclude-user = ( "abuser", "guyidontlike", "exbf" )

dynamic MySQL vhosts

Note: We assume that you have LightTPD installed with MySQL support (mysql USE flag). Be aware that LightTPD only support one type of vhost enabled at a time. You should comment other vhost configration options before inserting the MySQL vhost options.

We are going to setup LightTPD to support vhosts in a MySQL database.

First, edit your lighttpd.conf configuration file to include the MySQL options.

File: /etc/lighttpd/lighttpd.conf
# {{{ mod_mysql_vhost
mysql-vhost.db       = "lighttpd"
mysql-vhost.hostname = "<datebase_host_ip>"
mysql-vhost.user     = "<your_dbuser>"
mysql-vhost.pass     = "<your_dbuser_pass>"
mysql-vhost.sock     = "/var/run/mysqld/mysqld.sock"
mysql-vhost.sql      = "SELECT docroot FROM domains WHERE domain = '?';"
# }}}

Create an mysql database and create the table.

Code: Creating the database
mysql#>create database lighttpd;
mysql#>use lighttpd;
mysql#>CREATE TABLE `domains` (
  `domain_id` int(11) NOT NULL auto_increment,
  `domain` varchar(64) NOT NULL,
  `docroot` varchar(128) NOT NULL default ''
  PRIMARY KEY  (`domain_id`)

Insert vhosts with phpMyAdmin or with the command line. Just fill the fields 'domain' and 'docroot'. Make sure that lighttpd has proper rights to the docroot folder.

Tweaking using dynamic activate/deactivate option

We need to tweak these settings to support multiple LightTPD servers on a single MySQL database. We'll also include support for enabling/disabling vhosts in the database, without deleting the vhost.

Edit the LightTPD configuration file. The SQL query needs some adjustment in order to support multiple server and dynamic enabling/disabling of vhosts. The query in the configuration can be adapted to your needs. Just make sure that the vhost name is return in a single field, called domain.

File: /etc/lighttpd/lighttpd.conf
mysql-vhost.sql      = "SELECT docroot FROM domains WHERE server = '<lighttpd_server_ip>' AND enabled = 'y' AND domain = '?';"

Now add the two fields to your LightTPD domains table

Code: Alter the table
 mysql#>ALTER TABLE domains ADD `server` varchar(15) NOT NULL,  `enabled` enum('y','n') NOT NULL;

You can now fill the field 'server' with the IP Address of the lighttpd server running the vhost. To enable the vhost, set the 'enabled' field to 'y'. To disable an vhost, set the 'enabled' field to 'n'. Changes are immediately effective. This can be perfectly implemented to a hosting company.


Static compression (HTML)

Firstly you need to activate the "mod_compress" module. This is done by commenting out "mod_compress" in /etc/lighttpd/lighttpd.conf. Finally it should look like:

File: /etc/lighttpd/lighttpd.conf
server.modules = (

Then you need to create a directory where all the cache-files are being stored. We're using /tmp/lighttpd/cache/compress. By default, LightTPD will store those files in /var/lib/lighttpd/cache/compress.

 mkdir -p /tmp/lighttpd/cache/compress

The compression directory mentioned in the cache-dir line should be owned by the user who runs the LightTPD daemon. Now we set the new path in the lighttpd.conf and enable compression for the content-types text/plain and text/html.

File: /etc/lighttpd/lighttpd.conf
compress.cache-dir = "/tmp/lighttpd/cache/compress/"
compress.filetype = ("text/plain","text/html")

Dynamic compression (PHP)

To enable dynamic compression, you need to enable zlib.output_compression in your php.ini:

File: php.ini
zlib.output_compression = On

To find out the path of your php.ini, check the output of:

Code: Show PHP's configuration file names
  php --ini

Starting LightTPD

To start LightTPD, you can use the init scripts provided:

Code: Starting LightTPD
 # /etc/init.d/lighttpd start
 * Starting lighttpd ...                  [ ok ]

Point your web browser to, and, if you are successful, you should get a 404 Not Found. All files are stored in /var/www/localhost/htdocs. If LightTPD did not start up properly, check out the file /var/log/lighttpd/error.log

Starting LighTPD when your computer boots

This will add LightTPD to the default run level of your computer:

Code: Adding LightTPD to the default run level
 # rc-update add lighttpd default
 * lighttpd added to runlevel default
Retrieved from ""

Last modified: Fri, 15 Aug 2008 12:37:00 +0000 Hits: 33,913