Module mod_fastcgi

mod_fastcgi is not compiled into the server by default. To use mod_fastcgi you first copy src/mod_fastcgi.c from this kit into your Apache server's source directory. Then you add the following line to the server build Configuration file:

        Module fastcgi_module    mod_fastcgi.o

There are several ways to direct HTTP requests to FastCGI applications:

• SetHandler can associate the handler fastcgi-handler with a specific file, or all the files in a directory.

• AddHandler can associate the handler fastcgi-handler with files based on file extension.

• ForceType can associate the MIME type application/x-httpd-fcgi with a specific file, or all the files in a directory.

• AddType can associate the MIME type application/x-httpd-fcgi with files based on file extension.

• AddFastCgiAuth and AuthFastCgi can associate any keyword with a FastCGI authentication script on a per directory basis.

Summary

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 website (http://www.fastcgi.com/).

Directives

• AppClass
• FastCgiIpcDir
• AddFastCgiAuth
• AuthFastCgi

The AppClass directive starts one or more FastCGI application processes, using the executable file exec-path. mod_fastcgi will restart these processes should they die.

When a client requests the file exec-path, the request is handled first by the mod_fastcgi module. mod_fastcgi communicates the request to a process in the application class, which generates the response. mod_fastcgi relays this response back to the client.

The optional parameters to the AppClass directive are as follows:

• processes: number of FastCGI processes that the Web server will spawn, default 1.

• listen-queue-depth: depth of listen queue shared by the processes, default 5. A deeper listen queue allows the server to cope with transient load fluctuations without rejecting requests; it does not increase throughput. Adding extra processes may increase throughput, depending upon the application and the host.

• restart-delay: number of seconds between restarts of processes in this class, default 5. When the first process dies it will be restarted immediately, but if a second process from this class dies within restart-delay seconds, it will not be restarted until restart-delay seconds have passed since the previous restart. This delay prevents a broken application from soaking up too much of the system. Default value is 5 seconds.

• priority: priority of FastCGI application processes, as defined by the setpriority system call. The default value is zero, i.e. same priority as the HTTP server. Negative values are not allowed.

• initial-env: a name-value pair in the initial environment passed to the application processes. The argument has the form name=value, with no whitespace allowed. You can add several name-value pairs to the initial environment by using this option several times. The default initial environment is empty (no name-value pairs.)

Errors possible in the AppClass directive include syntax errors, arguments out of range, and the file exec-path being non-existent or not executable.

FastCgiIpcDir

The FastCgiIpcDir directive controls where mod_fastcgi creates Unix-domain sockets for communicating with the applications it manages.

By default, mod_fastcgi creates the sockets in /tmp. The socket names have the form OM_WS_n.pid where n is a sequence number and pid is the process ID of the Apache parent process. If your system runs a periodic job to delete files from /tmp, and it deletes these files, your Web server won't be able to communicate with its FastCGI applications.

To avoid this problem place a FastCgiIpcDir directive before the AppClass directives in your server configuration. Specify a directory that's readable, writeable, and searchable by the account you use for your Web server, but otherwise not accessible to anyone.

Note 1 below describes platform-specific problems in moving the sockets out of /tmp; please read it.

AddFastCgiAuth

The AddFastCgiAuth directive works in conjunction with the AuthFastCgi directive to provide per directory authentication support for mod_fastcgi. AddFastCgiAuth associates a keyword with an FastCGI authentication server. The keyword provides a server-wide means of referring to an authenticator for any directory in which it is used. Multiple AddFastCgiAuth directives are permitted, allowing many authenticators to be referenced.

AuthFastCgi

The AuthFastCgi directive works in conjuction with the AuthFastCgi directive to provide per directory authentication support for mod_fastcgi. AuthFastCgi is used in Directory or Location stanzas to specify which FastCGI authenticator should be referenced when requests resolve to this path. AuthType Basic and AuthName realm-name should be specified in the stanza with the AuthFastCgi directive. For example:

httpd.conf:

AppClass /server-root/auth/authftp.fcgi -initial-env FTP_HOST=plato.ibmus2.ibm.com
AddFastCgiAuth auth-keyword /server-root/auth/authftp.fcgi

access.conf:

<Directory /server-root/secret-docs>
AuthType Basic
AuthName realm
AuthFastCgi auth-keyword
<Limit GET POST>
require valid-user
</Limit>

Important notes

1. On some platforms, Unix-domain sockets don't work when stored in non-local file systems. Digital UNIX 3.0 is known to have this problem with NFS (fixed in Digital UNIX 3.2); Solaris 2.5 is known to have this problem with AFS. If /tmp is part of a local file system you'll avoid this problem by leaving the listening sockets in /tmp rather than using the FastCgiIpcDir directive to put them somewhere else.

2. Error logging by the mod_fastcgi process manager corrupts the error log on some platforms, due to a bug in the C library function fopen. For instance, SunOS 4.1.4 has the fopen bug and exhibits the error log corruption problem. A corrupted error log makes it difficult to debug problems on your Web server. You should apply the following patch to Apache 1.1.1 in order to eliminate the possibility of this problem:

   % diff -c alloc.c alloc.c.orig
   *** alloc.c     Mon Sep 23 17:45:34 1996
   --- alloc.c.orig        Mon Sep 23 17:43:16 1996
   ***************
   *** 765,784 ****
     
     FILE *pfopen(struct pool *a, char *name, char *mode)
     {
   !   FILE *fd = NULL;
     
       block_alarms();
   !   if (*mode == 'a') {
   !     /* Work around faulty implementations of fopen */
   !     int baseFlag = (*(mode+1) == '+') ? O_RDWR : O_WRONLY;
   !     int desc = open(name, baseFlag | O_APPEND | O_CREAT,
   !             S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH);
   !     if (desc >= 0) {
   !       fd = fdopen(desc, mode);
   !     }
   !   } else {
   !     fd = fopen(name, mode);
   !   }
       if (fd != NULL) note_cleanups_for_file (a, fd);
       unblock_alarms();
       return fd;
   --- 765,774 ----
     
     FILE *pfopen(struct pool *a, char *name, char *mode)
     {
   !   FILE *fd;
     
       block_alarms();
   !   fd = fopen(name, mode);
       if (fd != NULL) note_cleanups_for_file (a, fd);
       unblock_alarms();
       return fd;
       

3. The ScriptAlias directive takes priority over the AddType directive: A file located in a directory that is the target of ScriptAlias is always handled by the handler cgi-handler (mod_cgi.) So don't put FastCGI applications in a ScriptAlias directory -- the applications won't work properly!

4. mod_fastcgi does not implement TCP/IP connections to FastCGI applications, only Unix Domain socket connections. To connect to remote FastCGI applications run the cgi-fcgi program as a CGI script. See the cgi-fcgi manpage for more information.

5. The optional module mod_env provides two directives (PassEnv and SetEnv) that are designed for passing environment variables to CGI scripts. These directives also work for passing per-request environment variables to FastCGI applications. To pass initial environment variables you must use the -initial-env option to AppClass.

6. mod_fastcgi becomes confused if you put a slash at the end of your DocumentRoot. The symptom is that the request handler won't find any of the applications that you have defined using AppClass.

7. mod_fastcgi does not implement the Authorizer or Filter roles described in the FastCGI specification. However, you can approximate the Filter role using Apache's Action directive to route requests to a FastCGI Responder. See the documentation for mod_actions for information on the Action directive.

8. See the README file for a complete list of known bugs in this version of mod_fastcgi.

   Example

   What follows is a minimal httpd.conf for Apache 1.1.1 and FastCGI Developer's Kit 1.5. Use this configuration for initial testing with FastCGI. When you've verified that this configuration works, you can merge the FastCGI-specific aspects of this configuration with your own configuration.

   Directions:

   1. Change $APACHE to the path name of the directory containing your Apache 1.1.1 kit, i.e. the directory containing the Apache 1.1.1 README. For instance, you might change $APACHE to /udir/doe/apache_1.1.1.

      Change $FASTCGI to the path name of the directory containing your FastCGI Developer's Kit 1.5, i.e. the directory containing the FastCGI Developer's Kit 1.5 README. For instance, you might change $FASTCGI to /udir/doe/fcgi-devel-kit.

      Save the resulting file as $APACHE/conf/httpd.conf.

   2. Build Apache 1.1.1 with mod_fastcgi. This creates the httpd executable.

      Build the FastCGI Developer's Kit 1.5. This creates the echo executable that you are going to run as a FastCGI application.

   3. In a shell, cd to $APACHE and start httpd:

          % src/httpd -f $APACHE/conf/httpd.conf
          

   4. Use a browser to access the URL

          http://$YOUR_HOST:5556/examples/echo
          

      where $YOUR_HOST is the IP address of the host running httpd. Look for STATE=TEXAS in the initial environment that echo displays. The request counter should increment each time you reload the page.

   # httpd.conf -- minimal for mod_fastcgi
   #
   # One config file is plenty
   ResourceConfig /dev/null
   AccessConfig   /dev/null
   
   # Not starting httpd as root, so Port must be larger than 1023
   Port 5556
   
   # This is what you'd add to the config if the server is to be
   # started as root.  Don't do this until you've verified that the
   # server works when started as non-root!  Don't use user/group nobody;
   # define a new user and group specfifically for running the server.
   # User httpd
   # Group httpd
   
   # Configure just one idle httpd child process, to simplify debugging
   StartServers    1
   MinSpareServers 1
   MaxSpareServers 1
   
   # Tell httpd where it should live, turn on access and error logging
   ServerRoot     $APACHE
   ErrorLog       logs/error.log
   TransferLog    logs/access.log
   ScoreBoardFile logs/httpd.scoreboard
   
   # Tell httpd where to get documents
   # XXX: No slash allowed at the end of DocumentRoot!
   DocumentRoot $FASTCGI
   
   # This is how you'd place the Unix-domain socket files in the logs
   # directory (you'd probably want to create a subdirectory for them.)
   # Don't do this until you've verified that everything works with
   # the socket files stored locally, in /tmp!
   # FastCgiIpcDir $APACHE/logs
   
   # Start the echo app
   AppClass $FASTCGI/examples/echo -initial-env STATE=TEXAS
   
   # Have mod_fastcgi handle requests for the echo app
   # (otherwise the server will return the app's binary as a file!)
   <Location /examples/echo>
   SetHandler fastcgi-script
   </Location>
   
   # This is how you'd have mod_fastcgi handle requests for all files
   # whose names end in .fcg.
   # AddHandler fastcgi-script fcg
   
   # End of httpd.conf
   

   ---