Module mod_fastcgi

This module is contained in the mod_fastcgi.c file. It provides for startup of and communication with FastCGI applications. This module is not compiled into the server by default. To use this module you must copy src/mod_fastcgi.c from this kit into your Apache server's source directory. Then you have to add the following line to the server build Configuration file.

Module fastcgi_module	mod_fastcgi.o

Any file with the MIME type application/x-httpd-fcgi will be processed by this module. Note that the ScriptAlias directive takes priority over the AddType directive; a file located in a directory that is the target of ScriptAlias directive will have type application/x-httpd-cgi and be handled by mod_cgi, regardless of its name. So don't put FastCGI applications in your /cgi-bin/ directory -- they won't work properly!

Summary

FastCGI is a faster alternative to CGI. FastCGI gets its speed by having the Web server keep the application processes running between requests. So, unlike CGI, you do not have the overhead of starting up a new process and doing application initialization each time somebody requests a document. The processes start up with the Web server and keep on running.

FastCGI applications communicate with a Web server using a simple communications protocol. A single full-duplex connection communicates the environment variables and stdin data to the application, and stdout and stderr data to the Web server.

For more information on FastCGI including freely available FastCGI server modules and application libraries, go to the FastCGI home page (http://www.fastcgi.com).

Any file that has a MIME type of application/x-httpd-fcgi and that has an Application Class associated with it will be treated as a FastCGI script. A file gets this MIME type by (a) not residing in a ScriptAlias directory and (b) having a name ending in an extension defined by an AddType application/x-httpd-fcgi directive. An Application Class is established by the AppClass directive.

Directives

AppClass

AppClass

Syntax: AppClass exec-path [-processes N] [-listen-queue-depth N] [-restart-delay N] [-priority N] [-initial-env name=value]
Context: srm.conf
Module: mod_fastcgi

The AppClass directive starts one or more FastCGI application processes, using the executable file exec-path. This file must have MIME type application/x-httpd-fcgi. The server is responsible for restarting these processes should they die. All of the FastCGI application processes started by a given AppClass directive share a common Unix domain listening socket.

When a a client request comes in for the file exec-path, the request is handled by the mod_fastcgi module. The FastCGI module connects the requests to a processes belonging to the corresponding application class.

The optional parameters to the AppClass directive are as follows:

processes: number of FastCGI processes that the server will spawn, default value is 1.
listen-queue-depth: depth of listening queue shared by the processes, default value is 5.
restart-delay: number of seconds before web server restarts a dead FastCGI process. The server will restart dead processes no more often than one every restart-delay seconds.
priority: priority of FastCGI processes, default value is same priority as the HTTP server.
initial-env: a name-value pair in the initial environment passed to the application processes. Several name-value pairs can be specified by using this option several times. The default initial environment is empty (no name-value pairs).

If there are any errors in processing the FastCGI directive AppClass, the server will exit with appropriate error messages. Errors include syntax errors, exec-path having incorrect MIME-type, exec-path does not exist.

Example

In srm.conf

AddType application/x-httpd-fcgi .fcgi
Alias /fcgi-bin/ /usr/local/etc/httpd/fcgi-devel-kit/examples/
AppClass /usr/local/etc/httpd/fcgi-devel-kit/examples/tiny-fcgi.fcgi -processes 2

In this example if a request comes in for /fcgi-bin/tiny-fcgi.fcgi it'll be bound to the application class defined above, and the request would get sent to one of the 2 tiny-fcgi.fcgi processes.

Note: To try this configuration example with the FastCGI Developer's Kit, you need to make a link from the name examples/tiny-fcgi.fcgi to the existing file examples/tiny-fcgi.