[APACHE DOCUMENTATION]

Module mod_fastcgi

This module is contained in the mod_fastcgi.c file. It provides a high-performance alternative to CGI for writing Web server applications in a variety of languages, including Perl, C, C++, Java, and Python.

Any request for a file with the MIME type application/x-httpd-fcgi will be processed by mod_fastcgi. For the request to succeed, the server's configuration must have started the application (executable file) using the AppClass directive.

This module is included optionally in Apache 1.2 and later.

Summary

FastCGI is a high-performance 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 (e.g. connecting to a database) 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/).

Directives


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. 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:

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

Syntax: FastCgiIpcDir dir-path
Context: srm.conf
Module: mod_fastcgi

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, writable, 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.


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 ScriptAliasdirective has type application/x-httpd-cgi and is handled by mod_cgi. So don't put FastCGI applications in your /cgi-bin/ directory -- they won't work properly!

  4. 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 the applications that you have defined using AppClass.

  5. mod_fastcgi does not know about environment variables defined by the optional module mod_env. Use the -initial-env option to AppClass.

  6. 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.

    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, and makes the echo.fcg link to this application. This link gives it a distinctive MIME type so that mod_fastcgi will handle it.

    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.fcg
          
      where $YOUR_HOST is the IP address of the host running httpd. Look for STATE=TEXAS in the initial environment that echo.fcg displays.

    # 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
    
    # 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
    
    # Tell Apache that mod_fastcgi should handle files ending in .fcg
    AddType application/x-httpd-fcgi .fcg
    
    # 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 the server works with
    # the socket files stored locally, in /tmp.
    # FastCgiIpcDir $APACHE/logs
    
    # Start the echo.fcg application (echo.fcg is a sym-link to echo,
    # created by $FASTCGI/examples/Makefile.)
    AppClass $FASTCGI/examples/echo.fcg -initial-env STATE=TEXAS
    
    # End of httpd.conf
    

    The manual translated into Japanese is here.

    Index Home