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.
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/).
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:
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.
setpriority
system call. The default
value is zero, i.e. same priority as the HTTP server. Negative
values are not allowed.
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
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.
/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.
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;
ScriptAlias
directive takes priority over the
AddType
directive; a file located in a directory that
is the target of ScriptAlias
directive 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!
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
.
mod_fastcgi
does not know about environment
variables defined by the optional module mod_env
.
Use the -initial-env
option to
AppClass
.
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.
Directions:
$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
.
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.
$APACHE
and start httpd:
% src/httpd -f $APACHE/conf/httpd.conf
http://$YOUR_HOST:5556/examples/echo.fcgwhere
$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