Frequently Asked Questions (FAQs)¶

.

Help: Where can I get Help?¶

.

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)

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 still get a 403 status, even though the permissions on my doc root directory and its contents are set to 755?¶

Nine times out of ten (in IRC support), you have forgotten to check the permissions on one of the parent directories. Double check each directory in your path to insure 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 available from? it's mentioned in docs but not available in the distributed package (1.3.7)¶

If you install lighttpd (http://lighttpd.net/download/INSTALL), the spawn-fcgi binary is installed automatically (on versions < 1.4.23).
It is now a seperate package living at: http://redmine.lighttpd.net/projects/spawn-fcgi

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 = ( "/" => ... )
}

You can also use server.error-handler-404 to redirect all non-existent files to FastCGI (see LighttpdOnRails for an example), but you should not. It is known to have unexpected side effects and is more a hack than a real solution. Use mod_magnet whenever you need such changes, darix provides very good scripts (which should fit a lot of web apps)

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 on how to Migrate from Apache¶

Do you support .htaccess files?¶

No. lighttpd's design does not permit implementing this functionality as config files are loaded at startup time and .htaccess would be needed to be parsed at request time.
Also scanning all the directories in the request path for those files can cause significant slowdown especially because lighttpd is single process and is single threaded.
Furthermore, .htaccess files are Apache config files. We would need to write a parser and it might not even be possible to map all functionality to lighttpd logic.

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 MigratingFromApache