docs/mod_fastcgi.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <HTML>
   3     <!-- $Id: mod_fastcgi.html,v 1.35 2004/01/07 02:02:31 robs Exp $ -->
   4     <HEAD>
   5         <TITLE>
   6             Apache module mod_fastcgi
   7         </TITLE>
   8 <STYLE TYPE="text/css">
   9  body {
  10   background-color: #ffffff;
  11   color: #000000;
  12  }
  13  :link { color: #0000ff }
  14  :visited { color: #000080 }
  15  :active { color: #ff0000 }
  16  h3.c3 {text-align: center}
  17  h1.c2 {text-align: center}
  18  p.c1 {text-align: center}
  19 </STYLE>
  20     </HEAD>
  21     <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
  22     <BODY>
  23         <P CLASS="c1">
  24             <IMG SRC="http://httpd.apache.org/docs/images/sub.gif" ALT="[APACHE FEATHER BANNER]" WIDTH="500" HEIGHT=
  25             "62">
  26         </P>
  27         <H1 CLASS="c2">
  28             Module mod_fastcgi
  29         </H1>
  30         <P>
  31             This 3<SUP>rd</SUP> party module provides support for the FastCGI protocol. FastCGI is a language
  32             independent, scalable, open extension to CGI that provides high performance and persistence without the
  33             limitations of server specific APIs.
  34         </P>
  35         <P>
  36             FastCGI applications are not limited to a particular development language (the protocol is open). FastCGI
  37             application libraries currently exist for Perl, C/C++, Java, Python, TCL, SmallEiffel, and Smalltalk.
  38         </P>
  39         <P>
  40             FastCGI applications use TCP or Unix sockets to communicate with the web server. This scalable architecture
  41             allows applications to run on the same platform as the web server or on many machines scattered across an
  42             enterprise network.
  43         </P>
  44         <P>
  45             FastCGI applications are portable to other web server platforms. FastCGI is supported either directly or
  46             through commercial extensions by most popular web servers.
  47         </P>
  48         <P>
  49             FastCGI applications are fast because they&#39;re persistent. There is no per-request startup and
  50             initialization overhead. This makes possible the development of applications which would otherwise be
  51             impractical within the CGI paradigm (e.g. a huge Perl script, or an application which requires a connection
  52             to one or more databases).
  53         </P>
  54         <P>
  55             See the FastCGI <A HREF="http://www.FastCGI.com/">website</A> for more information. To receive FastCGI
  56             related announcements and notifications of software updates, subscribe to <A HREF=
  57             "http://fastcgi.com/fastcgi-announce">fastcgi-announce</A>. To participate in the discussion of
  58             <CODE>mod_fastcgi</CODE> and FastCGI application development, subscribe to <A HREF=
  59             "http://fastcgi.com/fastcgi-developers">fastcgi-developers</A>.
  60         </P>
  61         <H2>
  62             Summary
  63         </H2>
  64         <P>
  65             For information about building and installing the module, see the <A HREF="../INSTALL">INSTALL</A> document
  66             that came with the distribution.
  67         </P>
  68         <P>
  69             FastCGI applications under <CODE>mod_fastcgi</CODE> are defined as one of three types: static, dynamic, or
  70             external. They&#39;re configured using the <A HREF="#fastcgiserver">FastCgiServer</A>, <A HREF=
  71             "#FastCgiConfig">FastCgiConfig</A>, and <A HREF="#FastCgiExternalServer">FastCgiExternalServer</A> <A HREF=
  72             "#directives">directives</A> respectively. Any URI that Apache identifies as a FastCGI application and
  73             which hasn&#39;t been explicitly configured using a <A HREF="#fastcgiserver">FastCgiServer</A> or <A HREF=
  74             "#FastCgiExternalServer">FastCgiExternalServer</A> directive is handled as a dynamic application (see the
  75             <A HREF="#FastCgiConfig">FastCgiConfig</A> directive for more information).
  76         </P>
  77         <P>
  78             FastCGI static and dynamic applications are spawned and managed by the FastCGI Process Manager, fcgi-pm.
  79             The process manager is spawned by Apache at server initialization. External applications are presumed to be
  80             started and managed independently.
  81         </P>
  82         <P>
  83             Apache must be configured to identify requests for FastCGI URIs. <CODE>mod_fastcgi</CODE> registers (with
  84             Apache) a handler type of <CODE>fastcgi-script</CODE> for this purpose.
  85         </P>
  86         <P>
  87             To configure Apache to handle all files (within the scope of the directive) as FastCGI applications (e.g.
  88             for a fcgi-bin directory):
  89         </P>
  90         <BLOCKQUOTE>
  91             <P>
  92                 <CODE><A HREF="http://httpd.apache.org/docs/mod/mod_mime.html#sethandler">SetHandler</A>
  93                 fastcgi-script</CODE>
  94             </P>
  95         </BLOCKQUOTE>
  96         <P>
  97             To configure Apache to handle files (within the scope of the directive) with the specified extension(s) as
  98             FastCGI applications:
  99         </P>
 100         <BLOCKQUOTE>
 101             <P>
 102                 <CODE><A HREF="http://httpd.apache.org/docs/mod/mod_mime.html#addhandler">AddHandler</A> fastcgi-script
 103                 fcg fcgi fpl</CODE>
 104             </P>
 105         </BLOCKQUOTE>
 106         <P>
 107             Consult the Apache documentation for more information regarding these and other directives which affect
 108             request handling (such as <CODE><A HREF=
 109             "http://httpd.apache.org/docs/mod/mod_actions.html#action">Action</A>).</CODE>
 110         </P>
 111         <P>
 112             Dynamic FastCGI applications require the <CODE>ExecCGI</CODE> option be enabled (see the <A HREF=
 113             "http://httpd.apache.org/docs/mod/core.html#options"><CODE>Options</CODE></A> directive) in the
 114             application&#39;s directory.
 115         </P>
 116         <H2>
 117             Notes
 118         </H2>
 119         <P>
 120             <CODE>mod_fastcgi</CODE> logs FastCGI application error (stderr) output to the server log associated with
 121             the request. Errors reported by the FastCGI process manager, fcgi-pm, are reported to the main server log
 122             (typically, logs/error_log). Data written to stdout or stderr before entering the FastCGI <EM>accept</EM>
 123             loop or via a mechanism that is not FastCGI protocol aware will also be directed to the main server log. If
 124             Apache&#39;s <A HREF="http://httpd.apache.org/docs/mod/core.html#loglevel"><CODE>LogLevel</CODE></A> is set
 125             to <CODE>info</CODE> additional informational messages are printed to the logs, these messages may be
 126             especially helpful while debugging a configuration.
 127         </P>
 128         <P>
 129             Under Unix, expect your FastCGI application to see SIGPIPE, SIGUSR1, and SIGTERM. The latest FastCGI C, C++
 130             and Perl application library installs default handlers if none are installed by the application. If an http
 131             client aborts a request before it completes, mod_fastcgi does too - this results in a SIGPIPE to the
 132             FastCGI application. At a minimum, SIGPIPE should be ignored (applications spawned by mod_fastcgi have this
 133             setup automatically). Ideally, it should result in an early abort of the request handling within your
 134             application and a return to the top of the FastCGI accept() loop. Apache uses SIGUSR1 to request a
 135             &quot;graceful&quot; process restart/shutdown. It is sent to Apache&#39;s process group (which includes
 136             applications spawned by mod_fastcgi). Ideally, it should result in a FastCGI application finishing the
 137             current request, if any, and then an exit. The mod_fastcgi process manager isn&#39;t particularly patient
 138             though (there&#39;s room for improvement here) and since it has to shutdown too, sends a SIGTERM to all of
 139             the FastCGI applications it is responsible for. Apache will restart the process manager and it will restart
 140             its managed applications (as if the server was just started). SIGTERM is, well, SIGTERM - your application
 141             should exit quickly.
 142         </P>
 143         <P>
 144             Under Windows, there are no signals. A shutdown event is used instead. This is setup by mod_fastcgi and
 145             honored by the latest version of the C, C++, and Perl application library. If your using a library which
 146             doesn&#39;t support this, your application will not get shutdown during an Apache restart/shutdown
 147             (there&#39;s room for improvement here).
 148         </P>
 149         <P>
 150             To pass per-request environment variables to FastCGI applications, have a look at: <A HREF=
 151             "http://httpd.apache.org/docs/mod/mod_env.html"><CODE>mod_env</CODE></A> (<CODE>SetEnv</CODE>,
 152             <CODE>PassEnv</CODE>, <CODE>UnSetEnv</CODE>), <A HREF=
 153             "http://httpd.apache.org/docs/mod/mod_setenvif.html"><CODE>mod_setenvif</CODE></A>
 154             (<CODE>BrowserMatch</CODE>, <CODE>BrowserMatchNoCase</CODE>, <CODE>SetEnvIf</CODE>,
 155             <CODE>SetEnvIfNoCase</CODE>), and <A HREF=
 156             "http://httpd.apache.org/docs/mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A> (if you&#39;re feeling
 157             adventurous).
 158         </P>
 159         <P>
 160             FastCGI application output is buffered by default. This is not the case for CGI scripts (under Apache 1.3).
 161             To override the default behavior, use the <CODE>-flush</CODE> option (not available for dynamic
 162             applications). Non-parsed header (nph-) scripts will be rejected by mod_fastcgi simply as warning the
 163             behavior is different (create a symbolic link to the script without the &quot;nph-&quot; prefix if this
 164             poses a problem).
 165         </P>
 166         <P>
 167             Redirects are handled similarly to CGI. Location headers with values that begin with &quot;/&quot; are
 168             treated as internal-redirects; otherwise, they are treated as external redirects (302).
 169         </P>
 170         <P>
 171             Session affinity (as well as distribution) should be achievable outside of <CODE>mod_fastcgi</CODE> using
 172             <A HREF="http://httpd.apache.org/docs/mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>. If you get this
 173             working, please post the details to <A HREF=
 174             "mailto:fastcgi-developers@fastcgi.com">fastcgi-developers@fastcgi.com</A> so they can be included here.
 175         </P>
 176         <H2>
 177             FastCGI Specification Compliance
 178         </H2>
 179         <P>
 180             The FastCGI specification is not implemented in its entirety and I&#39;ve deviated a bit as well resulting
 181             in some Apache specific features.
 182         </P>
 183         <P>
 184             The file descriptors for stdout and stderr are left open. This is prohibited by the specification. I
 185             can&#39;t see any reason to require that they be closed, and leaving them open prevents FastCGI
 186             applications which were not completely ported to FastCGI from failing miserably. This does not mean the
 187             applications shouldn&#39;t be fixed such that this doesn&#39;t occur, but is invaluable when using a
 188             3<SUP>rd</SUP> party library (without source code) which expects to be able to write to stderr. Anything
 189             written to stdout or stderr in this manner will be directed to the main server log.
 190         </P>
 191         <P>
 192             The Filter and Log Roles are not supported. The Filter Role has little value in Apache until the output of
 193             one handler can be piped into another (Apache 2.0 is expected to support this). The Log Role has some
 194             value, but Apache&#39;s &quot;piped logs&quot; feature is similar (and is even more CPU friendly).
 195         </P>
 196         <P>
 197             The FastCGI protocol supports a feature, described in the specificiation as &quot;multiplexing&quot;, that
 198             allows a single client-server connection to be simultaneously shared by multiple requests. This is not
 199             supported. This does *not* prevent FastCGI applications from supporting multiple simultaneous requests over
 200             independent connections. Of course, the application has to be specifically designed to do so by using a
 201             threaded or select/poll based server model.
 202         </P>
 203         <P>
 204             The Authorizer Role has three variations corresponding to three specific Apache request handling
 205             phases:&nbsp; Authentication, Authorization, and Access Control. <CODE>mod_fastcgi</CODE> sets up the
 206             (Apache specific) environment variable &quot;FCGI_APACHE_ROLE&quot; to indicate which Apache authorizer
 207             phase is being performed.
 208         </P>
 209         <P>
 210             Authorizers under <CODE>mod_fastcgi</CODE> are sent nearly all of the standard environment variables
 211             typically available to CGI/FastCGI request handlers including some explicitly precluded by the FastCGI
 212             specification (for authorizers); I didn&#39;t see the point in leaving them out. All headers returned by a
 213             FastCGI Authorizer in a successful response (Status: 200) are passed to sub-processes (CGI/FastCGI
 214             invocations) as environment variables rather than just those prefixed by <CODE>Variable-</CODE> as the
 215             FastCGI specification calls for; I didn&#39;t see the point in leaving them out either. FastCGI
 216             specification compliant authorizer behavior can be obtained by using the <CODE>-compat</CODE> option to the
 217             Auth server directives.
 218         </P>
 219         <P>
 220             Custom failure responses from FastCGI authorizer applications are not supported (speak up if you need
 221             this). See the <A HREF="http://httpd.apache.org/docs/mod/core.html#errordocument">ErrorDocument</A>
 222             directive for a workaround (a CGI/FastCGI application can serve the error document).
 223         </P>
 224         <H2>
 225             <A NAME="directives">Directives</A>
 226         </H2>
 227         <UL>
 228             <LI>
 229                 <A HREF="#FastCgiServer"><CODE>FastCgiServer</CODE></A>
 230             </LI>
 231             <LI>
 232                 <A HREF="#FastCgiConfig"><CODE>FastCgiConfig</CODE></A>
 233             </LI>
 234             <LI>
 235                 <A HREF="#FastCgiExternalServer"><CODE>FastCgiExternalServer</CODE></A>
 236             </LI>
 237             <LI>
 238                 <A HREF="#FastCgiIpcDir"><CODE>FastCgiIpcDir</CODE></A>
 239             </LI>
 240             <LI>
 241                 <A HREF="#FastCgiWrapper"><CODE>FastCgiWrapper</CODE></A>
 242             </LI>
 243             <LI>
 244                 <A HREF="#FastCgiAuthenticator"><CODE>FastCgiAuthenticator</CODE></A>
 245             </LI>
 246             <LI>
 247                 <A HREF="#FastCgiAuthenticatorAuthoritative"><CODE>FastCgiAuthenticatorAuthoritative</CODE></A>
 248             </LI>
 249             <LI>
 250                 <A HREF="#FastCgiAuthorizer"><CODE>FastCgiAuthorizer</CODE></A>
 251             </LI>
 252             <LI>
 253                 <A HREF="#FastCgiAuthorizerAuthoritative"><CODE>FastCgiAuthorizerAuthoritative</CODE></A>
 254             </LI>
 255             <LI>
 256                 <A HREF="#FastCgiAccessChecker"><CODE>FastCgiAccessChecker</CODE></A>
 257             </LI>
 258             <LI>
 259                 <A HREF="#FastCgiAccessCheckerAuthoritative"><CODE>FastCgiAccessCheckerAuthoritative</CODE></A>
 260             </LI>
 261         </UL>
 262         <HR>
 263         <H2>
 264             <A NAME="FastCgiServer">FastCgiServer</A>
 265         </H2>
 266         <!-- %plaintext &lt;?INDEX {\tt FastCgiServer} directive&gt; -->
 267         <TABLE BORDER="0" SUMMARY="">
 268             <TR>
 269                 <TD>
 270                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 271                     "Help"><STRONG>Syntax:</STRONG></A>
 272                 </TD>
 273                 <TD>
 274                     <CODE>FastCgiServer <EM>filename</EM> <EM>[option ...]</EM></CODE>
 275                 </TD>
 276             </TR>
 277             <TR>
 278                 <TD>
 279                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 280                     "Help"><STRONG>Context:</STRONG></A>
 281                 </TD>
 282                 <TD>
 283                     server config
 284                 </TD>
 285             </TR>
 286         </TABLE>
 287         <P>
 288             The <CODE>FastCgiServer</CODE> directive defines <EM>filename</EM> as a static FastCGI application. If the
 289             filename does not begin with a slash (/) then it is assumed to be relative to the <A HREF=
 290             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>.
 291         </P>
 292         <P>
 293             By default, the Process Manager will start one instance of the application with the default configuration
 294             specified (in parentheses) below. Should a static application instance die for any reason
 295             <CODE>mod_fastcgi</CODE> will spawn another to replace it and log the event (at the <CODE>warn</CODE> <A
 296             HREF="http://httpd.apache.org/docs/mod/core.html#loglevel"><CODE>LogLevel</CODE></A>).
 297         </P>
 298         <P>
 299             <EM>Option</EM> can be one of (case insensitive):
 300         </P>
 301         <DL>
 302             <DT>
 303                 <CODE><STRONG>-appConnTimeout <EM>n</EM></STRONG> (0 seconds)</CODE>
 304             </DT>
 305             <DD>
 306                 <STRONG>Unix:&nbsp;</STRONG> The number of seconds to wait for a connection to the FastCGI application
 307                 to complete or 0 to indicate a blocking <CODE>connect()</CODE> should be used. Blocking
 308                 <CODE>connect()</CODE>s have an OS dependent internal timeout<CODE>.</CODE> If the timeout expires, a
 309                 SERVER_ERROR results. For non-zero values, this is the amount of time used in a <CODE>select()</CODE>
 310                 to write to the file descriptor returned by a non-blocking <CODE>connect().</CODE> Non-blocking
 311                 <CODE>connect()</CODE>s are troublesome on many platforms. See also <CODE>-idle-timeout</CODE>, it
 312                 produces similar results but in a more portable manner.<BR>
 313                  <STRONG>Windows NT:&nbsp;</STRONG> TCP based applications work as above. Named pipe based applications
 314                 (static applications configured without the <CODE>-port</CODE> option and dynamic applications) use
 315                 this value successfully to limit the amount of time to wait for a connection (i.e. it&#39;s not
 316                 &quot;troublesome&quot;). By default, this is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in
 317                 mod_fastcgi.h).
 318             </DD>
 319             <DT>
 320                 <CODE><STRONG>-group <EM>groupname|#gid</EM></STRONG> (none)</CODE>
 321             </DT>
 322             <DD>
 323                 <STRONG>Unix (only):</STRONG> When <A HREF="#FastCgiWrapper">FastCgiWrapper</A> is in use, the group is
 324                 used to invoke the wrapper. The <CODE>-group</CODE> option must be used together with
 325                 <CODE>-user</CODE>.
 326             </DD>
 327             <DT>
 328                 <CODE><STRONG>-idle-timeout <EM>n</EM></STRONG> (30 seconds)</CODE>
 329             </DT>
 330             <DD>
 331                 The number of seconds of FastCGI application inactivity allowed before the request is aborted and the
 332                 event is logged (at the <CODE>error</CODE> <A HREF=
 333                 "http://httpd.apache.org/docs/mod/core.html#loglevel"><CODE>LogLevel</CODE></A>). The inactivity timer
 334                 applies only as long as a connection is pending with the FastCGI application. If a request is queued to
 335                 an application, but the application doesn&#39;t respond (by writing and flushing) within this period,
 336                 the request will be aborted. If communication is complete with the application but incomplete with the
 337                 client (the response is buffered), the timeout does not apply.
 338             </DD>
 339             <DT>
 340                 <CODE><STRONG>-initial-env <EM>name[=[value]]</EM></STRONG> (none)</CODE>
 341             </DT>
 342             <DD>
 343                 A name-value pair to be passed in the FastCGI application&#39;s <EM>initial</EM> environment. To pass a
 344                 variable from Apache&#39;s environment, don&#39;t provide the &quot;=&quot; (if the variable isn&#39;t
 345                 actually in the environment, it will be defined without a value). To define a variable without a value,
 346                 provide the &quot;=&quot; without any value. The option can be used repeatedly.
 347             </DD>
 348             <DT>
 349                 <CODE><STRONG>-init-start-delay <EM>n</EM></STRONG> (1 second)</CODE>
 350             </DT>
 351             <DD>
 352                 The minimum number of seconds between the spawning of instances of this application. This delay
 353                 decreases the demand placed on the system at server initialization.
 354             </DD>
 355             <DT>
 356                 <CODE><STRONG>-flush</STRONG> (none)</CODE>
 357             </DT>
 358             <DD>
 359                 Force a write to the client as data is received from the application. By default,
 360                 <CODE>mod_fastcgi</CODE> buffers data in order to free the application as quickly as possible.
 361             </DD>
 362             <DT>
 363                 <CODE><STRONG>-listen-queue-depth <EM>n</EM></STRONG> (100)</CODE>
 364             </DT>
 365             <DD>
 366                 The depth of <CODE>listen()</CODE> queue (also known as the backlog) shared by all of the instances of
 367                 this application. A deeper listen queue allows the server to cope with transient load fluctuations
 368                 without rejecting requests; it does not increase throughput. Adding additional application instances
 369                 may increase throughput/performance, depending upon the application and the host.
 370             </DD>
 371             <DT>
 372                 <CODE><STRONG>-min-server-life <EM>n</EM></STRONG> (30)</CODE>
 373             </DT>
 374             <DD>
 375                                 The minimum number of seconds the application must run for before its restart
 376                                 interval is increased to 600 seconds.  The server will get 3 tries to run for at least this
 377                                 number of seconds.
 378             </DD>
 379             <DT>
 380                 <CODE><STRONG>-pass-header <EM>header</EM></STRONG> (none)</CODE>
 381             </DT>
 382             <DD>
 383                 The name of an HTTP Request Header to be passed in the <EM>request</EM> environment. This option makes
 384                 available the contents of headers which are normally not available (e.g. Authorization) to a CGI
 385                 environment.
 386             </DD>
 387             <DT>
 388                 <CODE><STRONG>-port <EM>n</EM></STRONG> (none)</CODE>
 389             </DT>
 390             <DD>
 391                 The TCP port number (1-65535) the application will use for communication with the web server. This
 392                 option makes the application accessible from other machines on the network (as well as this one). The
 393                 <CODE>-socket</CODE> and <CODE>-port</CODE> options are mutually exclusive.
 394             </DD>
 395             <DT>
 396                 <CODE><STRONG>-priority <EM>n</EM></STRONG> (0)</CODE>
 397             </DT>
 398             <DD>
 399                 The process priority to be assigned to the application instances (using <CODE>setpriority()</CODE>).
 400             </DD>
 401             <DT>
 402                 <CODE><STRONG>-processes <EM>n</EM></STRONG> (1)</CODE>
 403             </DT>
 404             <DD>
 405                 The number of instances of the application to spawn at server initialization.
 406             </DD>
 407             <DT>
 408                 <CODE><STRONG>-restart-delay <EM>n</EM></STRONG> (5 seconds)</CODE>
 409             </DT>
 410             <DD>
 411                 The minimum number of seconds between the respawning of failed instances of this application. This
 412                 delay prevents a broken application from soaking up too much of the system.
 413             </DD>
 414             <DT>
 415                 <CODE><STRONG>-socket <EM>filename</EM></STRONG> (generated)</CODE>
 416             </DT>
 417             <DD>
 418                 <STRONG>Unix:&nbsp;</STRONG> The filename of the Unix domain socket that the application will use for
 419                 communication with the web server. The module creates the socket within the directory specified by
 420                 <CODE><A HREF="#FastCgiIpcDir">FastCgiIpcDir</A></CODE>. This option makes the application accessible
 421                 to other applications (e.g. <CODE>cgi-fcgi</CODE>) on the same machine or via an external FastCGI
 422                 application definition (<CODE><A HREF="#FastCgiExternalServer">FastCgiExternalServer</A></CODE>). If
 423                 neither the <CODE>-socket</CODE> nor the <CODE>-port</CODE> options are given, the module generates a
 424                 Unix domain socket filename. The <CODE>-socket</CODE> and <CODE>-port</CODE> options are mutually
 425                 exclusive.
 426             </DD>
 427             <DD>
 428                 <STRONG>Windows NT:&nbsp;</STRONG> The name of the named pipe that the application will use for
 429                 communication with the web server. The module creates the named pipe under the named pipe root
 430                 specified by <CODE><A HREF="#FastCgiIpcDir">FastCgiIpcDir</A></CODE>. This option makes the application
 431                 accessible to other applications (e.g. <CODE>cgi-fcgi</CODE>) on the same machine or via an external
 432                 FastCGI application definition (<CODE><A HREF=
 433                 "#FastCgiExternalServer">FastCgiExternalServer</A></CODE>). If neither the <CODE>-socket</CODE> nor the
 434                 <CODE>-port</CODE> options are given, the module generates a name for the named pipe. The
 435                 <CODE>-socket</CODE> and <CODE>-port</CODE> options are mutually exclusive.
 436             </DD>
 437             <DT>
 438                 <CODE><STRONG>-user <EM>username|#uid</EM></STRONG> (none)</CODE>
 439             </DT>
 440             <DD>
 441                 <STRONG>Unix (only):</STRONG> When <A HREF="#FastCgiWrapper">FastCgiWrapper</A> is in use, the user is
 442                 used to invoke the wrapper. The <CODE>-user</CODE> option must be used together with
 443                 <CODE>-group</CODE>.
 444             </DD>
 445         </DL>
 446         <HR>
 447         <H2>
 448             <A NAME="FastCgiConfig">FastCgiConfig</A>
 449         </H2>
 450         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 451         <TABLE BORDER="0" SUMMARY="">
 452             <TR>
 453                 <TD>
 454                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 455                     "Help"><STRONG>Syntax:</STRONG></A>
 456                 </TD>
 457                 <TD>
 458                     <CODE>FastCgiConfig <EM>option [option ...]</EM></CODE>
 459                 </TD>
 460             </TR>
 461             <TR>
 462                 <TD>
 463                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 464                     "Help"><STRONG>Context:</STRONG></A>
 465                 </TD>
 466                 <TD>
 467                     server config
 468                 </TD>
 469             </TR>
 470         </TABLE>
 471         <P>
 472             The <CODE>FastCgiConfig</CODE> directive defines the default parameters for <EM>all</EM> dynamic FastCGI
 473             applications. This directive does not affect static or external applications in any way.
 474         </P>
 475         <P>
 476             Dynamic applications are not started at server initialization, but upon demand. If the demand is heavy,
 477             additional application instances are started. As the demand fades, application instances are killed off.
 478             Many of the options govern this process.
 479         </P>
 480         <P>
 481             <EM>Option</EM> can be one of (case insensitive):
 482         </P>
 483         <DL>
 484             <DT>
 485                 <CODE><STRONG>-appConnTimeout <EM>n</EM></STRONG> (0 seconds)</CODE>
 486             </DT>
 487             <DD>
 488                 <STRONG>Unix:&nbsp;</STRONG> The number of seconds to wait for a connection to the FastCGI application
 489                 to complete or 0 to indicate a blocking <CODE>connect()</CODE> should be used. Blocking
 490                 <CODE>connect()</CODE>s have an OS dependent internal timeout. If the timeout expires, a SERVER_ERROR
 491                 results. For non-zero values, this is the amount of time used in a <CODE>select()</CODE> to write to
 492                 the file descriptor returned by a non-blocking <CODE>connect()</CODE>. Non-blocking
 493                 <CODE>connect()</CODE>s are troublesome on many platforms. See also <CODE>-idle-timeout</CODE>, it
 494                 produces similar results but in a more portable manner.<BR>
 495                  <STRONG>Windows NT:&nbsp;</STRONG> TCP based applications work as above. Named pipe based applications
 496                 (static applications configured without the <CODE>-port</CODE> option and dynamic applications) use
 497                 this value successfully to limit the amount of time to wait for a connection (i.e. it&#39;s not
 498                 &quot;troublesome&quot;). By default, this is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in
 499                 mod_fastcgi.h).
 500             </DD>
 501             <DT>
 502                 <CODE><STRONG>-autoUpdate</STRONG> (none)</CODE>
 503             </DT>
 504             <DD>
 505                 Causes mod_fastcgi to check the modification time of the application on disk before processing each
 506                 request. If the application on disk has been changed, the process manager is notified and all running
 507                 instances of the application are killed off. In general, it&#39;s preferred that this type of
 508                 functionality be built-in to the application (e.g. every 100th request it checks to see if there&#39;s
 509                 a newer version on disk and exits if so). There may be an outstanding problem (bug) when this option is
 510                 used with <CODE>-restart</CODE>.
 511             </DD>
 512             <DT>
 513                 <CODE><STRONG>-flush</STRONG> (none)</CODE>
 514             </DT>
 515             <DD>
 516                 Force a write to the client as data is received from the application. By default,
 517                 <CODE>mod_fastcgi</CODE> buffers data in order to free the application as quickly as possible.
 518             </DD>
 519             <DT>
 520                 <CODE><STRONG>-gainValue <EM>n</EM></STRONG> (0.5)</CODE>
 521             </DT>
 522             <DD>
 523                 A floating point value between 0 and 1 used as an exponent in the computation of the exponentially
 524                 decayed connection times load factor of the currently running dynamic FastCGI applications. Old values
 525                 are scaled by (<CODE>1&nbsp;-&nbsp;gainValue</CODE>), so making it smaller weights old values more than
 526                 the current value (which is scaled by <CODE>gainValue</CODE>).
 527             </DD>
 528             <DT>
 529                 <CODE><STRONG>-idle-timeout <EM>n</EM></STRONG> (30 seconds)</CODE>
 530             </DT>
 531             <DD>
 532                 The number of seconds of FastCGI application inactivity allowed before the request is aborted and the
 533                 event is logged (at the <CODE>error</CODE> <A HREF=
 534                 "http://httpd.apache.org/docs/mod/core.html#loglevel"><CODE>LogLevel</CODE></A>). The inactivity timer
 535                 applies only as long as a connection is pending with the FastCGI application. If a request is queued to
 536                 an application, but the application doesn&#39;t respond (by writing and flushing) within this period,
 537                 the request will be aborted. If communication is complete with the application but incomplete with the
 538                 client (the response is buffered), the timeout does not apply.
 539             </DD>
 540             <DT>
 541                 <CODE><STRONG>-initial-env <EM>name[=[value]]</EM></STRONG> (none)</CODE>
 542             </DT>
 543             <DD>
 544                 A name-value pair to be passed in the initial environment when instances of applications are spawned.
 545                 To pass a variable from the Apache environment, don&#39;t provide the &quot;=&quot; (if the variable
 546                 isn&#39;t actually in the environment, it will be defined without a value). To define a variable
 547                 without a value, provide the &quot;=&quot; without any value. The option can be used repeatedly.
 548             </DD>
 549             <DT>
 550                 <CODE><STRONG>-init-start-delay <EM>n</EM></STRONG> (1 second)</CODE>
 551             </DT>
 552             <DD>
 553                 The minimum number of seconds between the spawning of instances of applications. This delay decreases
 554                 the demand placed on the system at server initialization.
 555             </DD>
 556             <DT>
 557                 <CODE><STRONG>-killInterval <EM>n</EM></STRONG> (300 seconds)</CODE>
 558             </DT>
 559             <DD>
 560                 Determines how often the dynamic application instance killing policy is implemented within the process
 561                 manager. Smaller numbers result in a more aggressive policy, larger numbers a less aggressive policy.
 562             </DD>
 563             <DT>
 564                 <CODE><STRONG>-listen-queue-depth <EM>n</EM></STRONG> (100)</CODE>
 565             </DT>
 566             <DD>
 567                 The depth of <CODE>listen()</CODE> queue (also known as the backlog) shared by all instances of
 568                 applications. A deeper listen queue allows the server to cope with transient load fluctuations without
 569                 rejecting requests; it does not increase throughput. Adding additional application instances may
 570                 increase throughput/performance, depending upon the application and the host.
 571             </DD>
 572             <DT>
 573                 <CODE><STRONG>-maxClassProcesses <EM>n</EM></STRONG> (10)</CODE>
 574             </DT>
 575             <DD>
 576                 The maximum number of dynamic FastCGI application instances allowed to run for any one FastCGI
 577                 application. It must be &lt;= to -maxProcesses (this is not programmatically enforced).
 578             </DD>
 579             <DT>
 580                 <CODE><STRONG>-maxProcesses <EM>n</EM></STRONG> (50)</CODE>
 581             </DT>
 582             <DD>
 583                 The maximum total number of dynamic FastCGI application instances allowed to run at any one time. It
 584                 must be &gt;= to -maxClassProcesses (this is not programmatically enforced).
 585             </DD>
 586             <DT>
 587                 <CODE><STRONG>-min-server-life <EM>n</EM></STRONG> (30)</CODE>
 588             </DT>
 589             <DD>
 590                                 The minimum number of seconds a dynamic FastCGI application must run for before its restart
 591                                 interval is increased to 600 seconds.  The server will get 3 tries to run for at least this
 592                                 number of seconds.
 593             </DD>
 594             <DT>
 595                 <CODE><STRONG>-minProcesses <EM>n</EM></STRONG> (5)</CODE>
 596             </DT>
 597             <DD>
 598                 The minimum total number of dynamic FastCGI application instances allowed to run at any one time
 599                 without being killed off by the process manager (due to lack of demand).
 600             </DD>
 601             <DT>
 602                 <CODE><STRONG>-multiThreshold <EM>n</EM></STRONG> (50)</CODE>
 603             </DT>
 604             <DD>
 605                 An integer between 0 and 100 used to determine whether any one instance of a FastCGI application should
 606                 be terminated. If the application has more than one instance currently running, this attribute will be
 607                 used to decide whether one of them should be terminated. If only one instance remains,
 608                 <CODE>singleThreshold</CODE> is used instead.<BR>
 609                  For historic reasons the mis-spelling <CODE>multiThreshhold</CODE> is also accepted.
 610             </DD>
 611             <DT>
 612                 <CODE><STRONG>-pass-header <EM>header</EM></STRONG> (none)</CODE>
 613             </DT>
 614             <DD>
 615                 The name of an HTTP Request Header to be passed in the <EM>request</EM> environment. This option makes
 616                 available the contents of headers which are normally not available (e.g. Authorization) to a CGI
 617                 environment.
 618             </DD>
 619             <DT>
 620                 <CODE><STRONG>-priority <EM>n</EM></STRONG> (0)</CODE>
 621             </DT>
 622             <DD>
 623                 The process priority to be assigned to the application instances (using <CODE>setpriority()</CODE>).
 624             </DD>
 625             <DT>
 626                 <CODE><STRONG>-processSlack <EM>n</EM></STRONG> (5)</CODE>
 627             </DT>
 628             <DD>
 629                 If the sum of the number of all currently running dynamic FastCGI applications and
 630                 <CODE>processSlack</CODE> exceeds <CODE>maxProcesses</CODE>, the process manager invokes the killing
 631                 policy. This is to improve performance at higher loads by killing some of the most inactive application
 632                 instances before reaching <CODE>maxProcesses</CODE>.
 633             </DD>
 634             <DT>
 635                 <CODE><STRONG>-restart</STRONG> (none)</CODE>
 636             </DT>
 637             <DD>
 638                 Causes the process manager to restart dynamic applications upon failure (similar to static
 639                 applications).
 640             </DD>
 641             <DT>
 642                 <CODE><STRONG>-restart-delay <EM>n</EM></STRONG> (5 seconds)</CODE>
 643             </DT>
 644             <DD>
 645                 The minimum number of seconds between the respawning of failed instances of applications. This delay
 646                 prevents a broken application from soaking up too much of the system.
 647             </DD>
 648             <DT>
 649                 <CODE><STRONG>-singleThreshold <EM>n</EM></STRONG> (0)</CODE>
 650             </DT>
 651             <DD>
 652                 An integer between 0 and 100 used to determine whether the last instance of a FastCGI application can
 653                 be terminated. If the process manager computed load factor for the application is lower than the
 654                 specified threshold, the last instance is terminated. In order to make your executables run in the
 655                 &quot;idle&quot; mode for the long time, you would specify a value closer to 1, however if memory or
 656                 CPU time is of primary concern, a value closer to 100 would be more applicable. A value of 0 will
 657                 prevent the last instance of an application from being terminated; this is the default value, changing
 658                 it is not recommended (especially if <CODE>-appConnTimeout</CODE> is set).<BR>
 659                  For historic reasons the mis-spelling <CODE>singleThreshhold</CODE> is also accepted.
 660             </DD>
 661             <DT>
 662                 <CODE><STRONG>-startDelay <EM>n</EM></STRONG> (3 seconds)</CODE>
 663             </DT>
 664             <DD>
 665                 The number of seconds the web server waits patiently while trying to connect to a dynamic FastCGI
 666                 application. If the interval expires, the process manager is notified with hope it will start another
 667                 instance of the application. The <CODE>startDelay</CODE> must be less than <CODE>appConnTimeout</CODE>
 668                 to be effective.
 669             </DD>
 670             <DT>
 671                 <CODE><STRONG>-updateInterval <EM>n</EM></STRONG> (300 seconds)</CODE>
 672             </DT>
 673             <DD>
 674                 The updateInterval determines how often statistical analysis is performed to determine the fate of
 675                 dynamic FastCGI applications.
 676             </DD>
 677         </DL>
 678         <HR>
 679         <H2>
 680             <A NAME="FastCgiExternalServer">FastCgiExternalServer</A>
 681         </H2>
 682         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 683         <TABLE BORDER="0" SUMMARY="">
 684             <TR>
 685                 <TD>
 686                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 687                     "Help"><STRONG>Syntax:</STRONG></A>
 688                 </TD>
 689                 <TD>
 690                     <CODE>FastCgiExternalServer <EM>filename</EM> -host <EM>hostname:port [option ...]</EM></CODE>
 691                 </TD>
 692             </TR>
 693             <TR>
 694                 <TD>
 695                 </TD>
 696                 <TD>
 697                     <CODE>FastCgiExternalServer <EM>filename</EM> -socket <EM>filename [option ...]</EM></CODE>
 698                 </TD>
 699             </TR>
 700             <TR>
 701                 <TD>
 702                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 703                     "Help"><STRONG>Context:</STRONG></A>
 704                 </TD>
 705                 <TD>
 706                     server config
 707                 </TD>
 708             </TR>
 709         </TABLE>
 710         <P>
 711             The <CODE>FastCgiExternalServer</CODE> directive defines <EM>filename</EM> as an external FastCGI
 712             application. If <EM>filename</EM> does not begin with a slash (/) then it is assumed to be relative to the
 713             <A HREF="http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>. The <EM>filename</EM> does
 714             not have to exist in the local filesystem. URIs that Apache resolves to this <EM>filename</EM> will be
 715             handled by this external FastCGI application..
 716         </P>
 717         <P>
 718             External FastCGI applications are not started by the process manager, they are presumed to be started and
 719             managed &quot;external&quot; to Apache and mod_fastcgi. The FastCGI devkit provides a simple tool,
 720             <CODE>cgi-fcgi</CODE>, for starting FastCGI applications independent of the server (applications can also
 721             be <EM>self-starting</EM>, see the devkit).
 722         </P>
 723         <P>
 724             <EM>Option</EM> can be one of (case insensitive):
 725         </P>
 726         <DL>
 727             <DT>
 728                 <CODE><STRONG>-appConnTimeout <EM>n</EM></STRONG> (0 seconds)</CODE>
 729             </DT>
 730             <DD>
 731                 <STRONG>Unix:&nbsp;</STRONG> The number of seconds to wait for a connection to the FastCGI application
 732                 to complete or 0 to indicate a blocking <CODE>connect()</CODE> should be used. Blocking
 733                 <CODE>connect()</CODE>s have an OS dependent internal timeout. If the timeout expires, a SERVER_ERROR
 734                 results. For non-zero values, this is the amount of time used in a <CODE>select()</CODE> to write to
 735                 the file descriptor returned by a non-blocking <CODE>connect()</CODE>. Non-blocking
 736                 <CODE>connect()</CODE>s are troublesome on many platforms. See also <CODE>-idle-timeout</CODE>, it
 737                 produces similar results but in a more portable manner.<BR>
 738                  <STRONG>Windows NT:&nbsp;</STRONG> TCP based applications work as above. Named pipe based applications
 739                 (static applications configured without the <CODE>-port</CODE> option and dynamic applications) use
 740                 this value successfully to limit the amount of time to wait for a connection (i.e. it&#39;s not
 741                 &quot;troublesome&quot;). By default, this is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in
 742                 mod_fastcgi.h).
 743             </DD>
 744             <DT>
 745                 <CODE><STRONG>-group <EM>groupname|#gid</EM></STRONG> (none)</CODE>
 746             </DT>
 747             <DD>
 748                 <STRONG>Unix (only):</STRONG> When <A HREF="#FastCgiWrapper">FastCgiWrapper</A> is in use, the group is
 749                 used to invoke the wrapper. The <CODE>-group</CODE> option must be used together with
 750                 <CODE>-user</CODE>.
 751             </DD>
 752             <DT>
 753                 <CODE><STRONG>-idle-timeout <EM>n</EM></STRONG> (30 seconds)</CODE>
 754             </DT>
 755             <DD>
 756                 The number of seconds of FastCGI application inactivity allowed before the request is aborted and the
 757                 event is logged (at the <CODE>error</CODE> <A HREF=
 758                 "http://httpd.apache.org/docs/mod/core.html#loglevel"><CODE>LogLevel</CODE></A>). The inactivity timer
 759                 applies only as long as a connection is pending with the FastCGI application. If a request is queued to
 760                 an application, but the application doesn&#39;t respond (by writing and flushing) within this period,
 761                 the request will be aborted. If communication is complete with the application but incomplete with the
 762                 client (the response is buffered), the timeout does not apply.
 763             </DD>
 764             <DT>
 765                 <CODE><STRONG>-flush</STRONG> (none)</CODE>
 766             </DT>
 767             <DD>
 768                 Force a write to the client as data is received from the application. By default,
 769                 <CODE>mod_fastcgi</CODE> buffers data in order to free the application as quickly as possible.
 770             </DD>
 771             <DT>
 772                 <CODE><STRONG>-host <EM>hostname:port</EM></STRONG> (none)</CODE>
 773             </DT>
 774             <DD>
 775                 The hostname or IP address and TCP port number (1-65535) the application uses for communication with
 776                 the web server. The <CODE>-socket</CODE> and <CODE>-host</CODE> options are mutually exclusive.
 777             </DD>
 778             <DT>
 779                 <CODE><STRONG>-pass-header <EM>header</EM></STRONG> (none)</CODE>
 780             </DT>
 781             <DD>
 782                 The name of an HTTP Request Header to be passed in the <EM>request</EM> environment. This option makes
 783                 available the contents of headers which are normally not available (e.g. Authorization) to a CGI
 784                 environment.
 785             </DD>
 786             <DT>
 787                 <CODE><STRONG>-socket <EM>filename</EM></STRONG> (none)</CODE>
 788             </DT>
 789             <DD>
 790                 <STRONG>Unix:&nbsp;</STRONG> The filename of the Unix domain socket the application uses for
 791                 communication with the web server. The filename is relative to the <CODE><A HREF=
 792                 "#FastCgiIpcDir">FastCgiIpcDir</A></CODE>. The <CODE>-socket</CODE> and <CODE>-port</CODE> options are
 793                 mutually exclusive.
 794             </DD>
 795             <DD>
 796                 <STRONG>Windows NT:&nbsp;</STRONG> The name of the named pipe the application uses for communicating
 797                 with the web server. the name is relative to the <CODE><A HREF=
 798                 "#FastCgiIpcDir">FastCgiIpcDir</A></CODE>. The <CODE>-socket</CODE> and <CODE>-port</CODE> options are
 799                 mutually exclusive.
 800             </DD>
 801             <DT>
 802                 <CODE><STRONG>-user <EM>username|#uid</EM></STRONG> (none)</CODE>
 803             </DT>
 804             <DD>
 805                 <STRONG>Unix (only):</STRONG> When <A HREF="#FastCgiWrapper">FastCgiWrapper</A> is in use, the user is
 806                 used to invoke the wrapper. The <CODE>-user</CODE> option must be used together with
 807                 <CODE>-group</CODE>.
 808             </DD>
 809         </DL>
 810         <HR>
 811         <H2>
 812             <A NAME="FastCgiIpcDir">FastCgiIpcDir</A>
 813         </H2>
 814         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 815         <TABLE BORDER="0" SUMMARY="">
 816             <TR>
 817                 <TD>
 818                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 819                     "Help"><STRONG>Syntax:</STRONG></A>
 820                 </TD>
 821                 <TD>
 822                     <STRONG>Unix:&nbsp;</STRONG> <CODE>FastCgiIpcDir <EM>directory</EM></CODE>
 823                 </TD>
 824             </TR>
 825             <TR>
 826                 <TD>
 827                 </TD>
 828                 <TD>
 829                     <STRONG>Windows NT:&nbsp;</STRONG> <CODE>FastCgiIpcDir <EM>name</EM></CODE>
 830                 </TD>
 831             </TR>
 832             <TR>
 833                 <TD>
 834                     <A HREF=
 835                     "http://httpd.apache.org/docs/mod/directive-dict.html#Default"><STRONG>Default:</STRONG></A>
 836                 </TD>
 837                 <TD>
 838                     <STRONG>Unix/Apache:&nbsp;</STRONG> <CODE>FastCgiIpcDir logs/fastcgi</CODE>
 839                 </TD>
 840             </TR>
 841             <TR>
 842                 <TD>
 843                 </TD>
 844                 <TD>
 845                     <STRONG>Unix/Apache2:&nbsp;</STRONG> <CODE>FastCgiIpcDir RUNTIMEDIR/fastcgi</CODE>
 846                 </TD>
 847             </TR>
 848             <TR>
 849                 <TD>
 850                 </TD>
 851                 <TD>
 852                     <STRONG>Windows NT:&nbsp;</STRONG> <CODE>FastCgiIpcDir \\\\.\\pipe\\ModFastCgi\\</CODE>
 853                 </TD>
 854             </TR>
 855             <TR>
 856                 <TD>
 857                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 858                     "Help"><STRONG>Context:</STRONG></A>
 859                 </TD>
 860                 <TD>
 861                     server config
 862                 </TD>
 863             </TR>
 864         </TABLE>
 865         <P>
 866             <STRONG>Unix:&nbsp;</STRONG> The <CODE>FastCgiIpcDir</CODE> directive specifies <EM>directory</EM> as the
 867             place to store (and in the case of external FastCGI applications, find) the Unix socket files used for
 868             communication between the applications and the web server. If the directory does not begin with a slash (/)
 869             then it is assumed to be relative to the <A HREF=
 870             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>. If the directory doesn&#39;t exist,
 871             an attempt is made to create it with appropriate permissions. Do not specify a directory that is not on a
 872             local filesystem! If you use the default directory (or another directory within <CODE>/tmp</CODE>),
 873             <CODE>mod_fastcgi</CODE> will break if your system periodically deletes files from <CODE>/tmp</CODE>.
 874         </P>
 875         <P>
 876             <STRONG>Windows NT:&nbsp;</STRONG> The <CODE>FastCgiIpcDir</CODE> directive specifies <EM>name</EM> as the
 877             root for the named pipes used for communication between the application and the web server. The
 878             <EM>name</EM> must be in the form of <STRONG>\\\\.\\pipe\\</STRONG><EM>pipename</EM> (notice that the
 879             backslashes are escaped). The <EM>pipename</EM> can contain any character other than a backslash.
 880         </P>
 881         <P>
 882             The <CODE>FastCgiIpcDir</CODE> directive must precede any <A HREF=
 883             "#FastCgiServer"><CODE>FastCgiServer</CODE></A> or <A HREF=
 884             "#FastCgiExternalServer"><CODE>FastCgiExternalServer</CODE></A> directives (which make use of Unix
 885             sockets). The directory must be readable, writeable, and executable (searchable) by the web server, but
 886             otherwise should not be accessible to anyone.
 887         </P>
 888         <P>
 889             <CODE>FastCgiIpcDir</CODE> is typically used move the directory someplace more suitable (than the default)
 890             for the platform or to prevent multiple Apache instances from sharing FastCGI application instances.
 891         </P>
 892         <HR>
 893         <H2>
 894             <A NAME="FastCgiWrapper">FastCgiWrapper</A>
 895         </H2>
 896         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 897         <TABLE BORDER="0" SUMMARY="">
 898             <TR>
 899                 <TD>
 900                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 901                     "Help"><STRONG>Syntax:</STRONG></A>
 902                 </TD>
 903                 <TD>
 904                     <CODE>FastCgiWrapper <EM>On | Off | filename</EM></CODE>
 905                 </TD>
 906             </TR>
 907             <TR>
 908                 <TD>
 909                     <A HREF=
 910                     "http://httpd.apache.org/docs/mod/directive-dict.html#Default"><STRONG>Default:</STRONG></A>
 911                 </TD>
 912                 <TD>
 913                     <CODE>FastCgiWrapper Off</CODE>
 914                 </TD>
 915             </TR>
 916             <TR>
 917                 <TD>
 918                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 919                     "Help"><STRONG>Context:</STRONG></A>
 920                 </TD>
 921                 <TD>
 922                     server config
 923                 </TD>
 924             </TR>
 925         </TABLE>
 926         <P>
 927             <STRONG>Unix (only):</STRONG> The <CODE>FastCgiWrapper</CODE> directive is used to enable support for a
 928             wrapper such as <A HREF="http://httpd.apache.org/docs/suexec.html">suexec</A> (included with Apache in the
 929             support directory) or <A HREF="http://cgiwrap.sourceforge.net/">cgiwrap</A>. To use the same wrapper used
 930             by Apache, set <CODE>FastCgiWrapper</CODE> to <EM>On</EM> (NOTE - mod_fastcgi cannot reliably determine the
 931             wrapper used by Apache when built as a DSO). The <EM>On</EM> argument requires suexec be enabled in Apache
 932             (for CGI). To use a specific wrapper, specify a <EM>filename</EM>. If the filename does not begin with a
 933             slash (/) then it is assumed to be relative to the <A HREF=
 934             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>. The wrapper is used to invoke all
 935             FastCGI applications (in the future this directive will have directory context).
 936         </P>
 937         <P>
 938             When <CODE>FastCgiWrapper</CODE> is enabled, no assumptions are made about the target application and thus
 939             presence and permissions checks cannot be made. This is the responsibility of the wrapper.
 940         </P>
 941         <P>
 942             The wrapper is invoked with the following arguments: username, group, application. The username and group
 943             are determined as described below. The application is the &quot;filename&quot; Apache resolves the
 944             requested URI to (dynamic) or the filename provided as an argument to another FastCGI (server or
 945             authorizer) directive. These arguments may or may not be used by the wrapper (e.g. suexec uses them,
 946             cgiwrap parses the URI and ignores them). The environment passed to the wrapper is identical to the
 947             environment passed when a wrapper is not in use.
 948         </P>
 949         <P>
 950             When <CODE>FastCgiWrapper</CODE> is enabled, the location of static or external FastCGI application
 951             directives can be important. Under Apache 1.3, they inherit their user and group from the <CODE>user and
 952             group</CODE> of the virtual server in which they are defined. <CODE><A HREF=
 953             "http://httpd.apache.org/docs/mod/core.html#user">User</A></CODE> and <CODE><A HREF=
 954             "http://httpd.apache.org/docs/mod/core.html#group">Group</A></CODE> directives <I><U>must</U></I> precede
 955             FastCGI application definitions. Under Apache 2.0, the <CODE>-user</CODE> and <CODE>-group</CODE> options
 956             to <A HREF="#FastCgiServer">FastCgiServer</A> and <A HREF=
 957             "#FastCgiExternalServer">FastCgiExternalServer</A> directives must be used (dynamic applications still use
 958             the virtual server&#39;s user and group).
 959         </P>
 960         <P>
 961             Note that access to (use of) FastCGI applications is <U><I>not</I></U> limited to the virtual server in
 962             which they were defined. The application is used to service requests from any virtual server with the same
 963             user and group.
 964         </P>
 965         <P>
 966             If a request is received for a FastCGI application without an existing matching definition already running
 967             with the correct user and group, a dynamic instance of the application is started with the correct user and
 968             group. This can lead to multiple copies of the same application running with different user/group. If this
 969             is a problem, preclude navigation to the application from other virtual servers or configure the virtual
 970             servers with the same User and Group.
 971         </P>
 972         <P>
 973             See the Apache documentation for more information about suexec (make sure you fully understand the security
 974             implications).
 975         </P>
 976         <HR>
 977         <H2>
 978             <A NAME="FastCgiAuthenticator">FastCgiAuthenticator</A>
 979         </H2>
 980         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 981         <TABLE BORDER="0" SUMMARY="">
 982             <TR>
 983                 <TD>
 984                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
 985                     "Help"><STRONG>Syntax:</STRONG></A>
 986                 </TD>
 987                 <TD>
 988                     <CODE>FastCgiAuthenticator <EM>filename</EM> [-compat]</CODE>
 989                 </TD>
 990             </TR>
 991             <TR>
 992                 <TD>
 993                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
 994                     "Help"><STRONG>Context:</STRONG></A>
 995                 </TD>
 996                 <TD>
 997                     directory
 998                 </TD>
 999             </TR>
1000         </TABLE>
1001         <P>
1002             The <CODE>FastCgiAuthenticator</CODE> directive is used to define a FastCGI application as a per-directory
1003             authenticator. Authenticators verify the requestor is who he says he is by matching the provided username
1004             and password against a list or database of known users and passwords. FastCGI based authenticators are
1005             useful primarily when the user database is maintained within an existing independent program or resides on
1006             a machine other than the web server.
1007         </P>
1008         <P>
1009             If the FastCGI application <EM>filename</EM> does not have a corresponding static or external server
1010             definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/)
1011             then it is assumed to be relative to the <A HREF=
1012             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>.
1013         </P>
1014         <P>
1015             <CODE>FastCgiAuthenticator</CODE> is used within <A HREF=
1016             "http://httpd.apache.org/docs/mod/core.html#directory"><CODE>Directory</CODE></A> or <A HREF=
1017             "http://httpd.apache.org/docs/mod/core.html#location"><CODE>Location</CODE></A> containers and must include
1018             an <A HREF="http://httpd.apache.org/docs/mod/core.html#authtype"><CODE>AuthType</CODE></A> and <A HREF=
1019             "http://httpd.apache.org/docs/mod/core.html#authname"><CODE>AuthName</CODE></A> directive. Only the
1020             <CODE>Basic</CODE> user authentication type is supported. It must be accompanied by a <A HREF=
1021             "http://httpd.apache.org/docs/mod/core.html#require"><CODE>require</CODE></A> or <CODE><A HREF=
1022             "#FastCgiAuthorizer">FastCgiAuthorizer</A></CODE> directive in order to work correctly.
1023         </P>
1024         <BLOCKQUOTE>
1025 <PRE>
1026 &lt;Directory htdocs/protected&gt;
1027     AuthType Basic
1028     AuthName ProtectedRealm
1029     FastCgiAuthenticator fcgi-bin/authenticator
1030     require valid-user
1031 &lt;/Directory&gt;
1032 </PRE>
1033         </BLOCKQUOTE>
1034         <P>
1035             <CODE>mod_fastcgi</CODE> sends nearly all of the standard environment variables typically available to
1036             CGI/FastCGI request handlers. All headers returned by a FastCGI authentication application in a successful
1037             response (Status: 200) are passed to sub-processes (CGI/FastCGI invocations) as environment variables. All
1038             headers returned in an unsuccessful response are passed on to the client. FastCGI specification compliant
1039             behavior can be obtained by using the <CODE>-compat</CODE> option.
1040         </P>
1041         <P>
1042             <CODE>mod_fastcgi</CODE> sets the environment variable &quot;FCGI_APACHE_ROLE&quot; to
1043             &quot;AUTHENTICATOR&quot; to indicate which (Apache specific) authorizer phase is being performed.
1044         </P>
1045         <P>
1046             Custom failure responses from FastCGI authorizer applications are not (yet?) supported. See the <A HREF=
1047             "http://httpd.apache.org/docs/mod/core.html#errordocument">ErrorDocument</A> directive for a workaround (a
1048             FastCGI application can serve the document).
1049         </P>
1050         <HR>
1051         <H2>
1052             <A NAME="FastCgiAuthenticatorAuthoritative">FastCgiAuthenticatorAuthoritative</A>
1053         </H2>
1054         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
1055         <TABLE BORDER="0" SUMMARY="">
1056             <TR>
1057                 <TD>
1058                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
1059                     "Help"><STRONG>Syntax:</STRONG></A>
1060                 </TD>
1061                 <TD>
1062                     <CODE>FastCgiAuthenticatorAuthoritative <EM>On | Off</EM></CODE>
1063                 </TD>
1064             </TR>
1065             <TR>
1066                 <TD>
1067                     <A HREF=
1068                     "http://httpd.apache.org/docs/mod/directive-dict.html#Default"><STRONG>Default:</STRONG></A>
1069                 </TD>
1070                 <TD>
1071                     <CODE>FastCgiAuthenticatorAuthoritative On</CODE>
1072                 </TD>
1073             </TR>
1074             <TR>
1075                 <TD>
1076                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
1077                     "Help"><STRONG>Context:</STRONG></A>
1078                 </TD>
1079                 <TD>
1080                     directory
1081                 </TD>
1082             </TR>
1083         </TABLE>
1084         <P>
1085             Setting the <CODE>FastCgiAuthenticatorAuthoritative</CODE> directive explicitly to <EM>Off</EM> allows
1086             authentication to be passed on to lower level modules (as defined in the <CODE>Configuration</CODE> and
1087             <CODE>modules.c</CODE> files) if the FastCGI application fails to authenticate the user.
1088         </P>
1089         <P>
1090             A common use for this is in conjunction with a well protected <A HREF=
1091             "http://httpd.apache.org/docs/mod/mod_auth.html#authuserfile"><CODE>AuthUserFile</CODE></A> containing a
1092             few (administration related) users.
1093         </P>
1094         <P>
1095             By default, control is not passed on and an unknown user will result in an Authorization Required reply.
1096             Disabling the default should be carefully considered.
1097         </P>
1098         <HR>
1099         <H2>
1100             <A NAME="FastCgiAuthorizer">FastCgiAuthorizer</A>
1101         </H2>
1102         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
1103         <TABLE BORDER="0" SUMMARY="">
1104             <TR>
1105                 <TD>
1106                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
1107                     "Help"><STRONG>Syntax:</STRONG></A>
1108                 </TD>
1109                 <TD>
1110                     <CODE>FastCgiAuthorizer <EM>filename</EM> [-compat]</CODE>
1111                 </TD>
1112             </TR>
1113             <TR>
1114                 <TD>
1115                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
1116                     "Help"><STRONG>Context:</STRONG></A>
1117                 </TD>
1118                 <TD>
1119                     directory
1120                 </TD>
1121             </TR>
1122         </TABLE>
1123         <P>
1124             The <CODE>FastCgiAuthorizer</CODE> directive is used to define a FastCGI application as a per-directory
1125             authorizer. Authorizers validate whether an authenticated requestor is allowed access to the requested
1126             resource. FastCGI based authorizers are useful primarily when there is a dynamic component to the
1127             authorization decision such as a time of day or whether or not the user has paid his bills.
1128         </P>
1129         <P>
1130             If the FastCGI application <EM>filename</EM> does not have a corresponding static or external server
1131             definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/)
1132             then it is assumed to be relative to the <A HREF=
1133             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>.
1134         </P>
1135         <P>
1136             <CODE>FastCgiAuthorizer</CODE> is used within <A HREF=
1137             "http://httpd.apache.org/docs/mod/core.html#directory"><CODE>Directory</CODE></A> or <A HREF=
1138             "http://httpd.apache.org/docs/mod/core.html#location"><CODE>Location</CODE></A> containers and must include
1139             an <A HREF="http://httpd.apache.org/docs/mod/core.html#authtype"><CODE>AuthType</CODE></A> and <A HREF=
1140             "http://httpd.apache.org/docs/mod/core.html#authname"><CODE>AuthName</CODE></A> directive. It must be
1141             accompanied by an authentication directive such as <A HREF=
1142             "#FastCgiAuthenticator"><CODE>FastCgiAuthenticator</CODE></A>, <A HREF=
1143             "http://httpd.apache.org/docs/mod/mod_auth.html#authuserfile"><CODE>AuthUserFile</CODE></A>, <A HREF=
1144             "http://httpd.apache.org/docs/mod/mod_auth_db.html#authdbuserfile"><CODE>AuthDBUserFile</CODE></A> or <A
1145             HREF="http://httpd.apache.org/docs/mod/mod_auth_dbm.html#authdbmuserfile"><CODE>AuthDBMUserFile</CODE></A>
1146             in order to work correctly.
1147         </P>
1148         <BLOCKQUOTE>
1149 <PRE>
1150 &lt;Directory htdocs/protected&gt;
1151     AuthType Basic
1152     AuthName ProtectedRealm
1153     AuthDBMUserFile conf/authentication-database
1154     FastCgiAuthorizer fcgi-bin/authorizer
1155 &lt;/Directory&gt;
1156 </PRE>
1157         </BLOCKQUOTE>
1158         <P>
1159             <CODE>mod_fastcgi</CODE> sends nearly all of the standard environment variables typically available to
1160             CGI/FastCGI request handlers. All headers returned by a FastCGI authorizer application in a successful
1161             response (Status: 200) are passed to sub-processes (CGI/FastCGI invocations) as environment variables. All
1162             headers returned in an unsuccessful response are passed on to the client. FastCGI specification compliant
1163             behavior can be obtained by using the <CODE>-compat</CODE> option.
1164         </P>
1165         <P>
1166             <CODE>mod_fastcgi</CODE> sets the environment variable &quot;FCGI_APACHE_ROLE&quot; to
1167             &quot;AUTHORIZER&quot; to indicate which (Apache specific) authorizer phase is being performed.
1168         </P>
1169         <P>
1170             Custom failure responses from FastCGI authorizer applications are not (yet?) supported. See the <A HREF=
1171             "http://httpd.apache.org/docs/mod/core.html#errordocument">ErrorDocument</A> directive for a workaround (a
1172             FastCGI application can serve the document).
1173         </P>
1174         <HR>
1175         <H2>
1176             <A NAME="FastCgiAuthorizerAuthoritative">FastCgiAuthorizerAuthoritative</A>
1177         </H2>
1178         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
1179         <TABLE BORDER="0" SUMMARY="">
1180             <TR>
1181                 <TD>
1182                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
1183                     "Help"><STRONG>Syntax:</STRONG></A>
1184                 </TD>
1185                 <TD>
1186                     <CODE>FastCgiAuthorizerAuthoritative <EM>On | Off</EM></CODE>
1187                 </TD>
1188             </TR>
1189             <TR>
1190                 <TD>
1191                     <A HREF=
1192                     "http://httpd.apache.org/docs/mod/directive-dict.html#Default"><STRONG>Default:</STRONG></A>
1193                 </TD>
1194                 <TD>
1195                     <CODE>FastCgiAuthorizerAuthoritative On</CODE>
1196                 </TD>
1197             </TR>
1198             <TR>
1199                 <TD>
1200                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
1201                     "Help"><STRONG>Context:</STRONG></A>
1202                 </TD>
1203                 <TD>
1204                     directory
1205                 </TD>
1206             </TR>
1207         </TABLE>
1208         <P>
1209             Setting the <CODE>FastCgiAuthorizerAuthoritative</CODE> directive explicitly to <EM>Off</EM> allows
1210             authorization to be passed on to lower level modules (as defined in the <CODE>Configuration</CODE> and
1211             <CODE>modules.c</CODE> files) if the FastCGI application fails to authorize the user.
1212         </P>
1213         <P>
1214             By default, control is not passed on and an unauthorized user will result in an Authorization Required
1215             reply. Disabling the default should be carefully considered.
1216         </P>
1217         <HR>
1218         <H2>
1219             <A NAME="FastCgiAccessChecker">FastCgiAccessChecker</A>
1220         </H2>
1221         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
1222         <TABLE BORDER="0" SUMMARY="">
1223             <TR>
1224                 <TD>
1225                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
1226                     "Help"><STRONG>Syntax:</STRONG></A>
1227                 </TD>
1228                 <TD>
1229                     <CODE>FastCgiAccessChecker <EM>filename</EM> [-compat]</CODE>
1230                 </TD>
1231             </TR>
1232             <TR>
1233                 <TD>
1234                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
1235                     "Help"><STRONG>Context:</STRONG></A>
1236                 </TD>
1237                 <TD>
1238                     directory
1239                 </TD>
1240             </TR>
1241         </TABLE>
1242         <P>
1243             The <CODE>FastCgiAccessChecker</CODE> (suggestions for a better name are welcome) directive is used to
1244             define a FastCGI application as a per-directory access validator. The Apache Access phase precede user
1245             authentication and thus the decision to (dis)allow access to the requested resource is based on the HTTP
1246             headers submitted with the request. FastCGI based authorizers are useful primarily when there is a dynamic
1247             component to the access validation decision such as a time of day or whether or not a domain has paid his
1248             bills.
1249         </P>
1250         <P>
1251             If the FastCGI application <EM>filename</EM> does not have a corresponding static or external server
1252             definition, it is started as a dynamic FastCGI application. If the filename does not begin with a slash (/)
1253             then it is assumed to be relative to the <A HREF=
1254             "http://httpd.apache.org/docs/mod/core.html#serverroot">ServerRoot</A>.
1255         </P>
1256         <P>
1257             <CODE>FastCgiAccessChecker</CODE> is used within <A HREF=
1258             "http://httpd.apache.org/docs/mod/core.html#directory"><CODE>Directory</CODE></A> or <A HREF=
1259             "http://httpd.apache.org/docs/mod/core.html#location"><CODE>Location</CODE></A> containers.
1260         </P>
1261         <BLOCKQUOTE>
1262 <PRE>
1263 &lt;Directory htdocs/protected&gt;
1264     FastCgiAccessChecker fcgi-bin/access-checker
1265 &lt;/Directory&gt;
1266 </PRE>
1267         </BLOCKQUOTE>
1268         <P>
1269             <CODE>mod_fastcgi</CODE> sends nearly all of the standard environment variables typically available to
1270             CGI/FastCGI request handlers. All headers returned by a FastCGI access-checker application in a successful
1271             response (Status: 200) are passed to sub-processes (CGI/FastCGI invocations) as environment variables. All
1272             headers returned in an unsuccessful response are passed on to the client. FastCGI specification compliant
1273             behavior can be obtained by using the <CODE>-compat</CODE> option.
1274         </P>
1275         <P>
1276             <CODE>mod_fastcgi</CODE> sets the environment variable &quot;FCGI_APACHE_ROLE&quot; to
1277             &quot;ACCESS_CHECKER&quot; to indicate which (Apache specific) authorizer phase is being performed.
1278         </P>
1279         <P>
1280             Custom failure responses from FastCGI authorizer applications are not (yet?) supported. See the <A HREF=
1281             "http://httpd.apache.org/docs/mod/core.html#errordocument">ErrorDocument</A> directive for a workaround (a
1282             FastCGI application can serve the document).
1283         </P>
1284         <HR>
1285         <H2>
1286             <A NAME="FastCgiAccessCheckerAuthoritative">FastCgiAccessCheckerAuthoritative</A>
1287         </H2>
1288         <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
1289         <TABLE BORDER="0" SUMMARY="">
1290             <TR>
1291                 <TD>
1292                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Syntax" REL=
1293                     "Help"><STRONG>Syntax:</STRONG></A>
1294                 </TD>
1295                 <TD>
1296                     <CODE>FastCgiAccessCheckerAuthoritative <EM>On | Off</EM></CODE>
1297                 </TD>
1298             </TR>
1299             <TR>
1300                 <TD>
1301                     <A HREF=
1302                     "http://httpd.apache.org/docs/mod/directive-dict.html#Default"><STRONG>Default:</STRONG></A>
1303                 </TD>
1304                 <TD>
1305                     <CODE>FastCgiAccessCheckerAuthoritative On</CODE>
1306                 </TD>
1307             </TR>
1308             <TR>
1309                 <TD>
1310                     <A HREF="http://httpd.apache.org/docs/mod/directive-dict.html#Context" REL=
1311                     "Help"><STRONG>Context:</STRONG></A>
1312                 </TD>
1313                 <TD>
1314                     directory
1315                 </TD>
1316             </TR>
1317         </TABLE>
1318         <P>
1319             Setting the <CODE>FastCgiAccessCheckerAuthoritative</CODE> directive explicitly to <EM>Off</EM> allows
1320             access checking to be passed on to lower level modules (as defined in the <CODE>Configuration</CODE> and
1321             <CODE>modules.c</CODE> files) if the FastCGI application fails to allow access.
1322         </P>
1323         <P>
1324             By default, control is not passed on and a failed access check will result in a Forbidden reply. Disabling
1325             the default should be carefully considered.
1326         </P>
1327         <HR>
1328         <H3 CLASS="c3">
1329             <A HREF="http://www.FastCGI.com/">www.FastCGI.com</A>
1330         </H3>
1331     </BODY>
1332 </HTML>
1333