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. Application libraries are available from
the FastCGI website
(http://www.fastcgi.com/).
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
mod_fastcgi
will process any request for
the handler fastcgi-handler
or for
a file with the MIME type application/x-httpd-fcgi
.
For the request to succeed, the server's configuration must have
started the application (executable file) using the
AppClass
directive.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.
mod_mime
for more information.
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/).
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, 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.
/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
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!
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.
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
.
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
.
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.
README
file for a complete
list of known bugs in this version of mod_fastcgi
.
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
.
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.
$APACHE
and start httpd:
% src/httpd -f $APACHE/conf/httpd.conf
http://$YOUR_HOST:5556/examples/echowhere
$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