FastCGI

The FastCGI interface was created with speed in mind, while giving a programming environment almost equal to the CGI protocol. FastCGI distinguishes between Responders and Authenticators, both of which can get a request and issue a response. However, most FastCGI applications just use the Responder part of the protocol.

A FastCGI application runs in a while-loop, with the rest of the program being written in plain CGI style. As the program runs continuously, we can store data between requests; also the setup cost is removed for all requests but the first. A typical program would look like this (in most languages):

<startup>
while (FCGI_Accept())
<handle request>
<cleanup>

The FastCGI protocol comes with libraries for C, Perl and Java. In addition, there are FastCGI libraries in many programming languages. PHP even comes with an optional FastCGI-compatible interpreter. Visit http://www.fastcgi.org/ to find the library for your favorite language, or read Chapter 13 for real world examples.

We can configure FastCGI using mod_fastcgi with Lighttpd versions prior to 1.5.0:

server.modules += ("mod_fastcgi")
fastcgi.server = (
".cgi" => ( # suffix-match if it starts with "."
# List of servers load-balanced by Lighttpd
( "host" => "localhost", # FastCGI over TCP/IP
"port" => 1234 ),
# FastCGI over UNIX domain sockets
( "socket" => "/var/sock/lighttpd-fcgi.sock" ),
# FastCGI application started by Lighttpd
( "bin-path" => "/usr/bin/perl",
"docroot" => "/var/www/myperlapp" )
),
"/cgi-bin" => ( # prefix-match if it starts with "/"
( "bin-path" => "/usr/bin/php-fcgi",
"broken-scriptfilename" => "enable",
"min-procs" => 1,
"max-procs" => 4 # ... other options folllow
)
)
)

mod_fastcgi will load-balance the given servers. If we use the bin-path directive, it will even start them for us (until version 1.5.0, which comes with its own utility to do this). Let us have a detailed look at the options per server. As we see in our example, there are three ways to reach a server:

If we let Lighttpd start our FastCGI program, we also have some more options:

The entry "mode"=>"authorizer" tells Lighttpd to treat the FastCGI program as Authorizer. We can also set "mode" => "responder", but this is the default anyway. For Authorizers, the "docroot" entry is mandatory. For responders, it does not hurt to set "docroot", especially if the FastCGI program uses it somewhere.

The "check-local" entry can be enabled or disabled. If it is enabled, it tells Lighttpd to look for a local file in the "docroot" path at the given address, and sends out a 404 error if it does not find anything. This is useful for using scripting languages as FastCGI responders.

If Lighttpd detects a server outage, it will route the requests to the remaining servers and check regularly if the broken server comes up again. We can set the duration in seconds between such checks with the "disable-time" entry.

For PHP, if the "broken-scriptfilename" entry is enabled, Lighttpd will mangle the SCRIPT_FILENAME FastCGI environment entry so that PHP has a correct PATH_INFO. The allow-x-send-file allows a backend to put the response in a file (perhaps a cache), set a X-LIGHTTPD-send-file header and have Lighttpd send out the content of this file.

mod_fastcgi supplies two additional global options, but we will seldom use them:

fastcgi.map-extensions = ("php4" => "php")
# to handle php4 analog to php files.
fastcgi.debug = 1 # or 0 to disable debugging

Since the version 1.5.0, mod_proxy, mod_fastcgi, and mod_scgi have been pulled together to mod_proxy_core plus various backends. The configuration options are the same for all the modules and are explained below (mod_proxy_core and backends).