Frequently Asked Questions (FAQs)¶

.

Help: Where can I get Help?¶

.

• Table of contents
• Frequently Asked Questions (FAQs)
  • Help: Where can I get Help?
  • General
    • • Why won't lighttpd start?
      • Why is my lighttpd config not doing what I want it to do?
      • Why do requests to lighttpd time out? (first time setup)
      • How do I bind to more than one address?
      • What does %1/$1 mean?
      • Does lighttpd support HTTP/2?
      • What kind of environment does server.error-handler-404 set up?
      • Why is server.error-handler-404 serving 200 instead of 404?
      • How do I protect a directory with a password?
      • Why do I get 403 Forbidden?
  • FastCGI
    • • Where is the spawn-php program/script?
      • Is there an su-exec wrapper available?
      • How do I exclude a certain directory from FastCGI?
      • How do I handle requests for non-existent files with my scripting framework?
      • I get the error "No input file specified" when trying to use PHP
      • How many php CGI processes will lighttpd spawn?
  • Questions from Apache users
    • • Tips for Migrating from Apache
      • Does lighttpd support Apache .htaccess files?
      • Can I use Apache modules with lighttpd?
      • Can I use SVN over WebDAV with lighttpd?
      • What is lighttpd's equivalent to Apache's "Options +!MultiViews"?

.

General¶

Why won't lighttpd start?¶

Manually test the lighttpd config: lighttpd -tt -f /etc/lighttpd/lighttpd.conf and review the output.
Check the lighttpd error log for clues: e.g. /var/log/lighttpd/error.log
systemd often hides useful information, so systemctl status lighttpd is not sufficient. journalctl --unit=lighttpd sometimes helps.

Why is my lighttpd config not doing what I want it to do?¶

Print the lighttpd config: lighttpd -p -f /etc/lighttpd/lighttpd.conf and review the output. This is the complete config lighttpd sees.
It is recommended that you start from a simple, working configuration. Then, make one change at a time, restart lighttpd, and test the change.
lighttpd can be configured using DebugVariables to print additional debugging to the lighttpd error log (/var/log/lighttpd/error.log)

Why do requests to lighttpd time out? (first time setup)¶

If you are setting up lighttpd for the first time, then your system firewall might need to be configured to allow HTTP/HTTPS requests to reach lighttpd. If your system has firewall-cmd, then as root run:

firewall-cmd --permanent --zone=public --add-service=http
firewall-cmd --permanent --zone=public --add-service=https
firewall-cmd --reload
firewall-cmd --permanent --zone=public --list-services

How do I bind to more than one address?¶

Use server.bind and server.port to bind to the first port and then the $SERVER["socket"] conditional, which can have an empty body { }, to bind to the rest. For example, to bind to 192.0.2.1 port 80, and to bind to *:443 and [::]:443 (TLS/SSL ports)

server.port = 80
server.bind = "192.0.2.1" 
$SERVER["socket"] == ":443" { }
$SERVER["socket"] == "[::]:443" { }

More examples binding to IPv6

What does %1/$1 mean?¶

These are backreferences used by mod_rewrite and mod_redirect
%n is used to denote a backreference to the config conditional, and $n is used to backreference on the redirect/rewrite regex.
If you need to learn about regexes, Regular-Expressions.info is a good place to start.

Does lighttpd support HTTP/2?¶

Yes, lighttpd 1.4.56 and later support HTTP/2.
lighttpd 1.4.59 enables HTTP/2 support by default.
lighttpd 1.4.56 - lighttpd 1.4.58 can enable HTTP/2 support using: server.feature-flags += ( "server.h2proto" => "enable", "server.h2c" => "enable" )
lighttpd does not implement HTTP/2 PUSH. You can use the HTTP Link response header to achieve similar behavior.

You can test lighttpd HTTP/2 support using curl:
curl -v --http2 https://www.example.org/
curl -v --http2 http://www.example.org/
curl -v --http2-prior-knowledge http://www.example.org/

What kind of environment does server.error-handler-404 set up?¶

The environment (which is relevant when using CGI or FastCGI) is quite normal, but observe the following:

• REQUEST_URI is the original request, and has nothing to do with where the redirect points to.
• The rest of the CGI environment is based off the server.error-handler-404 target.
• QUERY_STRING is not set from the original request, so you have to parse the REQUEST_URI yourself to get it.
• PATH_INFO, similarly, is not set from the original request.
• SCRIPT_NAME is set according to the server.error-handler-404 target, not according to the original REQUEST_URI.
• REDIRECT_STATUS is the error status of the original request (e.g. 404 or 403) for which server.error-handler-404 is being called.

Why is server.error-handler-404 serving 200 instead of 404?¶

The status returned is the result of running the server.error-handler-404 target handler. Your target handler can check REDIRECT_STATUS and can choose to return that status instead of 200. If you just want to send a custom-404 errorpage, there use server.errorfile-prefix. For full control over all HTTP error status codes, see server.error-handler

How do I protect a directory with a password?¶

mod_auth
doc/authentication.txt
If you are converting from Apache, an example using htpasswd authentication: HowToAuthenticationFromMultipleFiles

Why do I get 403 Forbidden?¶

There can be many reasons why you might get a 403 Forbidden. Among the first places to check are the permissions on the files in the filesystem. Nine times out of ten (in IRC support), you have forgotten to check the permissions on one of the parent directories, in addition to the document root and its contents. Double check each directory in your path to ensure the lighttpd user can access the nested doc root. selinux and alike might also play tricks on you :)

FastCGI¶

Where is the spawn-php program/script?¶

spawn-php is a separate package.

Is there an su-exec wrapper available?¶

Not officially, but Sune Foldager coded one especially for lighttpd which you can grab here. It's very easy to use, but has not yet been extensively tested so a little caution is advised. On the other hand, the source is very small so it's easy to get a security overview. Instructions and usage examples (with lighttpd) are in the README.

How do I exclude a certain directory from FastCGI?¶

# to exclude multiple directories: $HTTP["url"] !~ "^/(?:no-fcgi1|foo/no-fcgi2|bar)/" {
$HTTP["url"] !~ "^/no-fcgi/" {
   fastcgi.server = ( "/" => ... )
}

How do I handle requests for non-existent files with my scripting framework?¶

The recommended solution is url.rewrite-if-not-file
e.g. url.rewrite-if-not-file = ( "" => "/index.php?path=${url.path}${qsa}" )

A more general solution is mod_magnet with lua scripts. (See LighttpdOnRails for an example.)

url.rewrite-if-not-file or mod_magnet should be preferred to overloading server.error-handler-404 to redirect all non-existent files to FastCGI.

I get the error "No input file specified" when trying to use PHP¶

Sadly, this error message can mean a lot of things. A common explanation attempt: PHP is unable to locate or open the file which it is supposed to parse. This can have a lot of reasons:

• You forgot to add '''cgi.fix_pathinfo=1 to your php.ini''' file
  See the comments in the PHP docs. The issue here is that the environment variable SCRIPT_FILENAME is not being passed to PHP.
• Make sure you did not set doc_root or userdir in php.ini, or if you have set it, make sure it has the correct value (doc_root should match lighttpd's server.document-root option in this case)
• If open_basedir is set, make sure the requested file is below one of the directories which is specified there. In the past PHP parsed files which were not inside open_basedir as well, but this security problem was fixed (in php-5.2.3 or so).
• If you are running PHP with different permissions than lighttpd (spawn-fcgi with -u/-g, execwrap, suexec, ...), check that PHP can really read the file

If you are unable to find / fix the problem, you can use strace to see if it is a (OS-related) permission problem (look out for stat*(...YOURFILE...) = RETURNCODE). It might help to set max-procs to 1 and PHP_FCGI_CHILDREN as well (see fastcgi docs) in that case, so that you can easily attach strace to the correct php-cgi process.

How many php CGI processes will lighttpd spawn?¶

lighttpd has three configuration options that control how many php-cgi processes will run:

• PHP_FCGI_CHILDREN (defaults to 1)
• max-procs (default 4)
• min-procs (default max-procs)

When lighttpd starts, it will launch max-procs parent php processes. Each parent process then pre-forks PHP_FCGI_CHILDREN child processes. For example, if max-procs are 4 and PHP_FCGI_CHILDREN is 16, lighttpd will start max-procs x ( PHP_FCGI_CHILDREN + 1). In our case: 4 * ( 16 + 1 ) = 68 (4 watcher processes which do not handle requests, 64 real php backends which serve requests).

If you are using an opcode cache such as eAccelerator, XCache or similar it's advisable to keep max-procs at a very low number (1 is perfectly fine) and raise PHP_FCGI_CHILDREN instead. Those opcode caches will create a separate memory space for each parent process, otherwise, which is not what one would call "efficient memory usage" in that case.. If you leave max-procs at 4, you'll end up with four separate opcode memory cache segments.

Note that setting PHP_FCGI_MAX_REQUESTS is recommended to avoid possible memory leak side-effects.

Questions from Apache users¶

Tips for Migrating from Apache¶

Migrating from Apache

Does lighttpd support Apache .htaccess files?¶

No. Apache .htaccess files use Apache config syntax, not lighttpd config syntax. Apache .htaccess files are also very inefficient and are checked and processed in Apache for each and every request.

That being said, there are multiple ways to achieve .htaccess-like functionality in lighttpd

Can I use Apache modules with lighttpd?¶

No. Apache modules are not compatible with lighttpd.

Can I use SVN over WebDAV with lighttpd?¶

No. Use Apache. If you would like, you can proxy requests to Apache through lighttpd using mod_proxy.

What is lighttpd's equivalent to Apache's "Options +!MultiViews"?¶

See MultiViews