docs/mod_fastcgi.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <!-- $Id: mod_fastcgi.html,v 1.22 2001/05/12 12:53:57 robs Exp $ -->
   4
   5 <head>
   6 <title>Apache module mod_fastcgi</title>
   7 </head>
   8 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
   9
  10 <body BGCOLOR="#ffffff" TEXT="#000000" LINK="#0000ff" VLINK="#000080" ALINK="#ff0000">
  11
  12 <p align="center"><img SRC="http://www.apache.org/docs/images/sub.gif"
  13  ALT  ="[APACHE FEATHER BANNER]" width="500" height="62"> </p>
  14
  15 <h1 ALIGN="center">Module mod_fastcgi</h1>
  16
  17 <p>This 3<sup>rd</sup> party module provides support for the FastCGI protocol.
  18 FastCGI is a language independent, scalable, open extension to CGI that provides high
  19 performance and persistence without the limitations of server specific APIs.</p>
  20
  21 <p>FastCGI applications are not limited to a particular development language (the protocol
  22 is open). FastCGI application libraries currently exist for Perl, C/C++, Java, Python,
  23 and TCL.</p>
  24
  25 <p>FastCGI applications use (TCP or Unix) sockets to communicate with the web server.
  26 This scalable architecture allows applications to run on the same platform as the
  27 web server or on many machines scattered across an enterprise network.</p>
  28
  29 <p>FastCGI applications are portable to other web server platforms. FastCGI is
  30 supported either directly or through commercial extensions by most popular web servers.</p>
  31
  32 <p>FastCGI applications are fast because they're persistent. There is no per-request
  33 startup and initialization overhead. This makes possible the development of
  34 applications which would otherwise be impractical within the CGI paradigm (e.g. a huge
  35 Perl script, or an application which requires a connection to one or more databases).
  36 </p>
  37
  38 <p>For more information on FastCGI, go to the <a HREF="http://www.FastCGI.com/">FastCGI
  39 website</a>. To receive FastCGI related announcements and notifications of module
  40 updates, send mail to <A href="mailto:fastcgi-announce-request@fastcgi.com">fastcgi-announce-request@fastcgi.com</a>
  41 with "subscribe" in the Subject field. To participate in the discussion of
  42 <code>mod_fastcgi</code> and FastCGI application development, send mail to
  43 <A href="mailto:fastcgi-developers-request@fastcgi.com" >fastcgi-developers-request@fastcgi.com</a>
  44 with "subscribe" in the Subject field.</p>
  45
  46 <h2>Summary</h2>
  47
  48 <p>For information about building and installing the module, see the <A href="../INSTALL">INSTALL</a>
  49 document that came with the distribution.</p>
  50
  51 <p>FastCGI applications under <code>mod_fastcgi</code> are defined as one of three types:
  52 static, dynamic, or external. They're configured using the <A href="#fastcgiserver">FastCgiServer</a>,
  53 <A href="#FastCgiConfig">FastCgiConfig</a>, and <A href="#FastCgiExternalServer">FastCgiExternalServer</a>
  54 <A href="#directives">directives</a> respectively. Any URI that Apache identifies as
  55 a FastCGI application and which hasn't been explicitly configured using a
  56 <A href="#fastcgiserver" >FastCgiServer</a> or <A href="#FastCgiExternalServer">FastCgiExternalServer</a>
  57 directive is handled as a dynamic application (see the <A href="#FastCgiConfig">FastCgiConfig</a>
  58 directive for more information).</p>
  59
  60 <p>FastCGI static and dynamic applications are spawned and managed by the FastCGI Process
  61 Manager, fcgi-pm. The process manager is spawned by Apache at server initialization.
  62 External applications are presumed to be started and managed independently.</p>
  63
  64 <p>Apache must be configured to identify requests for FastCGI URIs. <code>mod_fastcgi</code>
  65 registers (with Apache) a handler type of <code>fastcgi-script</code> for this purpose.</p>
  66
  67 <p>To configure Apache to handle all files (within the scope of the directive) as FastCGI
  68 applications (e.g. for a fcgi-bin directory):</p>
  69
  70 <blockquote>
  71   <p><code><a href="http://www.apache.org/docs/mod/mod_mime.html#sethandler">SetHandler</a>
  72   fastcgi-script</code></p>
  73 </blockquote>
  74
  75 <p>To configure Apache to handle files (within the scope of the directive) with
  76 the specified extension(s) as FastCGI applications:</p>
  77
  78 <blockquote>
  79   <p><code><a href="http://www.apache.org/docs/mod/mod_mime.html#addhandler">AddHandler</a>
  80   fastcgi-script fcg fcgi fpl</code></p>
  81 </blockquote>
  82
  83 <dl>
  84   <p>Consult the Apache documentation for more information regarding these and other
  85   directives which affect request handling (such as <code>
  86   <a href="http://www.apache.org/docs/mod/mod_actions.html#action">Action</a>).</code></p>
  87   <p>Dynamic FastCGI applications require the <code>ExecCGI</code> option be enabled
  88   (see the <a href="http://www.apache.org/docs/mod/core.html#options"><code>Options</code></a>
  89   directive) in the application's directory.</p>
  90   <h2>Notes</h2>
  91   <p><code>mod_fastcgi</code> logs FastCGI application error (stderr) output to the server
  92   log associated with the request. Errors reported by the FastCGI process manager,
  93   fcgi-pm, are reported to the main server log (typically, logs/error_log).
  94   Data written to stdout or stderr before entering the FastCGI <em>accept</em>
  95   loop or via a mechanism that is not FastCGI protocol aware will also be
  96   directed to the main server log. If
  97   Apache's <a href="http://www.apache.org/docs/mod/core.html#loglevel"><code>LogLevel</code></a>
  98   is set to <code>info</code> additional informational messages are printed to the
  99   logs, these messages may be especially helpful while debugging a
 100   configuration..</p>
 101   <p>To pass per-request environment variables to FastCGI applications, have a look at:
 102   <a href="http://www.apache.org/docs/mod/mod_env.html"><code>mod_env</code></a>
 103   (<code>SetEnv</code>, <code>PassEnv</code>, <code>UnSetEnv</code>),
 104   <a href="http://www.apache.org/docs/mod/mod_setenvif.html"><code>mod_setenvif</code></a>
 105   (<code>BrowserMatch</code>, <code>BrowserMatchNoCase</code>, <code>SetEnvIf</code>,
 106   <code>SetEnvIfNoCase</code>), and
 107   <a href="http://www.apache.org/docs/mod/mod_rewrite.html"><code>mod_rewrite</code></a> (if
 108   you're feeling adventurous).</p>
 109   <p>FastCGI application output is buffered by default. This is not the case for CGI
 110   scripts (under Apache 1.3). To override the default behavior, use the <code>-flush</code>
 111   option (not available for dynamic applications). Non-parsed header (nph-) scripts will be rejected by mod_fastcgi simply as
 112   warning the behavior is different (create a symbolic link to the script without the
 113   "nph-" prefix if this poses a problem).</p>
 114   <p>Redirects are handled similarly to CGI. Location headers with values that begin
 115   with "/" are treated as internal-redirects; otherwise, they are treated as
 116   external redirects (302).</p>
 117   <p>Session affinity (as well as distribution) should be achievable outside of <code>mod_fastcgi</code>
 118   using <a href="http://www.apache.org/docs/mod/mod_rewrite.html"><code>mod_rewrite</code></a>.
 119   If you get this working, please post the details to
 120   <A href="mailto:fastcgi-developers@fastcgi.com">fastcgi-developers@fastcgi.com</a>
 121   so they can be included here.</p>
 122   <h2>FastCGI Specification Compliance</h2>
 123   <p>The FastCGI specification is not implemented in its entirety and I've deviated a bit as
 124   well resulting in some Apache specific features.</p>
 125   <p>The file descriptors for stdout and stderr are left open. This is
 126   prohibited by the specification. I can't see any reason to require that
 127   they be closed, and leaving them open prevents FastCGI applications which were
 128   not completely ported to FastCGI from failing miserably. This does not
 129   mean the applications shouldn't be fixed such that this doesn't occur, but is
 130   invaluable when using a 3<sup>rd</sup> party library (without source code) which expects
 131   to be able to write to stderr. Anything written to stdout or stderr in
 132   this manner will be directed to the main server log.</p>
 133   <p>The Filter and Log Roles are not supported. The Filter Role has
 134   little value in
 135   Apache until the output of one handler can be piped into another (Apache 2.0 is expected
 136   to support this). The Log Role has some value, but Apache's "piped
 137   logs" feature is similar (and is even more CPU friendly). </p>
 138   <p>Multiplexed requests are not supported. This does NOT mean FastCGI
 139   applications can't be multithreaded. It means that each request requires
 140   its own independent connect()/accept(). The protocol supports the concept of a
 141   connection simultaneously shared by multiple requests. The FastCGI application
 142   library which provides the FastCGI protocol support within FastCGI applications does not
 143   currently support it (and thus doesn't have to be supported here). This may become a
 144   higher priority when <code>mod_fastcgi</code> is ported to NT (Apache is threaded on
 145   NT which makes shared persistent multiplexed connection more reasonable to
 146   consider).</p>
 147   <p>The Authorizer Role has three variations corresponding to each three
 148   specific Apache request handling phases:&nbsp; Authentication, Authorization, and Access Control.
 149   <code>mod_fastcgi</code> sets up the (Apache specific) environment variable
 150   "FCGI_APACHE_ROLE" to indicate which Apache authorizer phase is being performed.</p>
 151   <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 152   typically available to CGI/FastCGI request handlers including some explicitly precluded by
 153   the FastCGI specification; I didn't see the point in leaving them out. All headers
 154   returned by a FastCGI authentication application in a successful response (Status: 200)
 155   are passed to sub-processes (CGI/FastCGI invocations) as environment variables rather than
 156   just those prefixed by <code>Variable-</code> as the FastCGI specification
 157   calls for; I didn't see the point in leaving them out either. FastCGI specification
 158   compliant authorizer behavior can be obtained by using the <code>-compat</code>
 159   option to the Auth server directives.</p>
 160   <p>Custom failure responses from FastCGI authorizer applications are not
 161   supported (speak up if you need this). See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 162   directive for a workaround (hint: a CGI/FastCGI application can serve the
 163   error document).</p>
 164   <h2><a name="directives">Directives</a></h2>
 165   <ul>
 166     <li><A href="#FastCgiServer"><code>FastCgiServer</code></a>
 167     <li><A href="#FastCgiConfig"><code>FastCgiConfig</code></a>
 168     <li><A href="#FastCgiExternalServer"><code>FastCgiExternalServer</code></a>
 169     <li><A href="#FastCgiIpcDir"><code>FastCgiIpcDir</code></a>
 170     <li><a href="#FastCgiWrapper"><code>FastCgiWrapper</code></a>
 171     <li><A href="#FastCgiAuthenticator"><code>FastCgiAuthenticator</code></a>
 172     <li><A href="#FastCgiAuthenticatorAuthoritative"><code>FastCgiAuthenticatorAuthoritative</code></a>
 173     <li><A href="#FastCgiAuthorizer"><code>FastCgiAuthorizer</code></a>
 174     <li><A href="#FastCgiAuthorizerAuthoritative"><code>FastCgiAuthorizerAuthoritative</code></a>
 175     <li><A href="#FastCgiAccessChecker"><code>FastCgiAccessChecker</code></a>
 176     <li><A href="#FastCgiAccessCheckerAuthoritative"><code>FastCgiAccessCheckerAuthoritative</code></a></li>
 177   </ul>
 178   <dd></dd>
 179 </dl>
 180
 181 <dl>
 182   <hr>
 183   <h2><a name="FastCgiServer">FastCgiServer</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiServer} directive&gt; -->
 184   <table border="0">
 185     <tr>
 186       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 187       <td><code>FastCgiServer <em>filename</em> <em>[option ...]</em></code></td>
 188     </tr>
 189     <tr>
 190       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 191       <td>server config</td>
 192     </tr>
 193   </table>
 194   <p>The <code>FastCgiServer</code> directive defines <em>filename</em> as a static FastCGI
 195   application. If the filename does not begin with a slash (/) then it is assumed to
 196   be relative to the <a href="http://www.apache.org/docs/mod/core.html#serverroot">ServerRoot</a>.
 197   </p>
 198   <p>By default, the Process Manager will start one instance of the application with the
 199   default configuration specified (in parentheses) below. Should a static application
 200   instance die for any reason <code>mod_fastcgi</code> will spawn another to replace it and
 201   log the event (at the <code>warn</code> <a href="http://www.apache.org/docs/mod/core.html#loglevel"><code>LogLevel</code></a>).</p>
 202   <p><em>Option</em> can be one of (case insensitive):</p>
 203
 204   <dt><code><b>-appConnTimeout <em>n</em></b> (0 seconds)</code>
 205   <dd><b>Unix:&nbsp;</b>The number of seconds to wait for a connection to the FastCGI application to
 206     complete or 0 to indicate a blocking <code>connect()</code> should be
 207     used. Blocking <code>connect()</code>s have an OS dependent internal
 208     timeout<code>. </code>If the timeout expires, a SERVER_ERROR results. For
 209     non-zero values, this is the amount of time used in a <code>select()</code>
 210     to write to the file descriptor returned by a non-blocking
 211     <code>connect().</code> Non-blocking <code>connect()</code>s are troublesome
 212     on many platforms. See also <code>-idle-timeout</code>, it produces similar results
 213     but in a more portable manner.<br>
 214  <b>Windows NT:&nbsp;</b>TCP based applications work as above. Named pipe based
 215   applications (static applications configured without the <code>-port</code> option and
 216   dynamic applications) use this value successfully to limit the amount of time
 217   to wait for a connection (i.e. it's not "troublesome"). By default, this
 218   is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in mod_fastcgi.h).
 219
 220   <dt><code><b>-idle-timeout <em>n</em></b> (30 seconds)</code>
 221   <dd>The number of seconds of FastCGI application inactivity allowed before the
 222     request is aborted and the event is logged (at the <code>error</code> <a href="http://www.apache.org/docs/mod/core.html#loglevel"><code>LogLevel</code></a>).
 223   The inactivity timer applies only as long as a connection is pending with the
 224   FastCGI application. If a request is queued to an application, but the
 225   application doesn't respond (by writing and flushing) within this period, the
 226   request will be aborted. If communication is complete with the
 227   application but incomplete with the client (the response is buffered), the
 228   timeout does not apply.
 229
 230   <dt><code><b>-initial-env <em>name[=[value]]</em></b> (none)</code>
 231   <dd>A name-value pair to be passed in the FastCGI application's <i>initial</i> environment. To
 232   pass a variable from Apache's environment, don't provide the "=" (if the
 233   variable isn't actually in the environment, it will be defined without a
 234   value). To define a variable without a value, provide the "=" without
 235   any value. The option can be used repeatedly.
 236
 237   <dt><code><b>-init-start-delay <em>n</em></b> (1 second)</code>
 238   <dd>The minimum number of seconds between the spawning of
 239   instances of this application. This delay decreases the demand placed
 240   on the system at server initialization.
 241
 242   <dt><code><b>-flush</b> (none)</code>
 243   <dd>Force a write to the client as data is received from the application. By default, <code>mod_fastcgi</code> buffers data in order to free the
 244   application as quickly as possible.
 245
 246   <dt><code><b>-listen-queue-depth <em>n</em></b> (100)</code>
 247   <dd>The depth of <code>listen()</code> queue (also known as the
 248   backlog) shared by all of the instances of this application. A deeper
 249   listen queue allows the server to cope with transient load fluctuations
 250   without rejecting requests; it does not increase throughput. Adding
 251   additional application instances may increase throughput/performance,
 252   depending upon the application and the host.
 253
 254   <dt><code><b>-pass-header <em>header</em></b> (none)</code>
 255   <dd>The name of an HTTP Request Header to be passed in the <i>request</i> environment. This option makes
 256   available the contents of headers which are normally not available (e.g.
 257   Authorization) to a CGI environment.
 258
 259   <dt><code><b>-port <em>n</em></b> (none)</code>
 260   <dd>The TCP port number (1-65535) the application will use for communication with the web
 261     server. This option makes the application accessible from other machines on the
 262     network (as well as this one). The <code>-socket</code> and <code>-port</code> options are mutually exclusive.
 263
 264   <dt><code><b>-priority <em>n</em></b> (0)</code>
 265   <dd>The process priority to be assigned to the application instances (using <code>setpriority()</code>).
 266
 267   <dt><code><b>-processes <em>n</em></b> (1)</code>
 268   <dd>The number of instances of the application to spawn
 269   at server initialization.
 270
 271   <dt><code><b>-restart-delay <em>n</em></b> (5 seconds)</code>
 272   <dd>The minimum number of seconds between the respawning
 273   of failed instances of this application. This delay prevents a broken
 274   application from soaking up too much of the system.
 275
 276   <dt><code><b>-socket <em>filename</em></b> (generated)</code>
 277   <dd><b>Unix:&nbsp</b>The filename of the Unix domain socket that the application will use for communication
 278     with the web server. The module creates the socket within the directory specified by
 279     <code><A href="#FastCgiIpcDir">FastCgiIpcDir</A></code>. This option makes the application accessible to other
 280     applications (e.g. <code>cgi-fcgi</code>) on the same machine or via an external FastCGI
 281     application definition (<code><A href="#FastCgiExternalServer">FastCgiExternalServer</A></code>). If neither the <code>-socket</code>
 282     nor the <code>-port</code> options are given, the module generates a Unix domain socket
 283     filename. The <code>-socket</code> and <code>-port</code> options are mutually exclusive.
 284
 285 <DD>
 286 <B>Windows NT:&nbsp</B>The name of the named pipe that the application will
 287 use for communication with the web server. The module creates the
 288 named pipe under the named pipe root specified by <code><A href="#FastCgiIpcDir">FastCgiIpcDir</A></code>.
 289 This option makes the application accessible to other applications (e.g.
 290 <code>cgi-fcgi</code>) on the same machine or via an external FastCGI application
 291 definition (<code><A href="#FastCgiExternalServer">FastCgiExternalServer</A></code>). If neither the <code>-socket</code>
 292 nor the <code>-port</code> options are given, the module generates a name for
 293 the named pipe. The <code>-socket</code> and <code>-port</code> options are
 294 mutually exclusive.</DD>
 295 </dl>
 296
 297 <dl>
 298   <hr>
 299   <h2><a NAME="FastCgiConfig">FastCgiConfig</a></h2>
 300   <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 301   <table border="0">
 302     <tr>
 303       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 304       <td><code>FastCgiConfig <em>option [option ...]</em></code></td>
 305     </tr>
 306     <tr>
 307       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 308       <td>server config</td>
 309     </tr>
 310   </table>
 311   <p>The <code>FastCgiConfig</code> directive defines the default parameters for
 312     <i>all</i> dynamic FastCGI applications. This directive does not affect static
 313     or external applications in any way.</p>
 314   <p>Dynamic applications are not started at server initialization, but upon demand.
 315     If the demand is heavy, additional application instances are started. As the
 316     demand fades, application instances are killed off. Many of the options govern
 317     this process.</p>
 318   <p><em>Option</em> can be one of (case insensitive):</p>
 319   <dt><code><b>-appConnTimeout <em>n</em></b> (0 seconds)</code>
 320   <dd><b>Unix:&nbsp;</b>The number of seconds to wait for a connection to the
 321     FastCGI application to complete or 0 to indicate a blocking <code>connect()</code>
 322     should be used. Blocking <code>connect()</code>s have an OS dependent internal
 323     timeout. If the timeout expires, a SERVER_ERROR results. For non-zero values,
 324     this is the amount of time used in a <code>select()</code> to write to the
 325     file descriptor returned by a non-blocking <code>connect()</code>. Non-blocking
 326     <code>connect()</code>s are troublesome on many platforms. See also <code>-idle-timeout</code>,
 327     it produces similar results but in a more portable manner.<br>
 328     <b>Windows NT:&nbsp;</b>TCP based applications work as above. Named pipe based
 329     applications (static applications configured without the <code>-port</code>
 330     option and dynamic applications) use this value successfully to limit the
 331     amount of time to wait for a connection (i.e. it's not "troublesome"). By
 332     default, this is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in mod_fastcgi.h).
 333   <dt><code><b>-autoUpdate</b> (none)</code>
 334   <dd>Causes mod_fastcgi to check the modification time of the application on
 335     disk before processing each request. If the application on disk has been changed,
 336     the process manager is notified and all running instances of the application
 337     are killed off. In general, it's preferred that this type of functionality
 338     be built-in to the application (e.g. every 100th request it checks to see
 339     if there's a newer version on disk and exits if so). There may be an outstanding
 340     problem (bug) when this option is used with <code>-restart</code>.
 341   <dt><code><b>-gainValue <em>n</em></b> (0.5)</code>
 342   <dd>A floating point value between 0 and 1 used as an exponent in the computation
 343     of the exponentially decayed connection times load factor of the currently
 344     running dynamic FastCGI applications. Old values are scaled by (<code>1&nbsp;-&nbsp;gainValue</code>),
 345     so making it smaller weights old values more than the current value (which
 346     is scaled by <code>gainValue</code>).
 347   <dt><code><b>-idle-timeout <em>n</em></b> (30 seconds)</code>
 348   <dd>The number of seconds of FastCGI application inactivity allowed before the
 349     request is aborted and the event is logged (at the <code>error</code> <a href="http://www.apache.org/docs/mod/core.html#loglevel"><code>LogLevel</code></a>).
 350     The inactivity timer applies only as long as a connection is pending with
 351     the FastCGI application. If a request is queued to an application, but the
 352     application doesn't respond (by writing and flushing) within this period,
 353     the request will be aborted. If communication is complete with the application
 354     but incomplete with the client (the response is buffered), the timeout does
 355     not apply.
 356   <dt><code><b>-initial-env <em>name[=[value]]</EM></b> (none)</code>
 357   <dd>A name-value pair to be passed in the initial environment when instances
 358     of applications are spawned. To pass a variable from the Apache environment,
 359     don't provide the "=" (if the variable isn't actually in the environment,
 360     it will be defined without a value). To define a variable without a value,
 361     provide the "=" without any value. The option can be used repeatedly.
 362   <dt><code><b>-init-start-delay <em>n</em></b> (1 second)</code>
 363   <dd>The minimum number of seconds between the spawning of instances of applications.
 364     This delay decreases the demand placed on the system at server initialization.
 365   <dt><code><b>-killInterval <em>n</em></b> (300 seconds)</code>
 366   <dd>Determines how often the dynamic application instance killing policy is
 367     implemented within the process manager. Smaller numbers result in a more aggressive
 368     policy, larger numbers a less aggressive policy.
 369   <dt><code><b>-listen-queue-depth <em>n</em></b> (100)</code>
 370   <dd>The depth of <code>listen()</code> queue (also known as the backlog) shared
 371     by all instances of applications. A deeper listen queue allows the server
 372     to cope with transient load fluctuations without rejecting requests; it does
 373     not increase throughput. Adding additional application instances may increase
 374     throughput/performance, depending upon the application and the host.
 375   <dt><code><b>-maxClassProcesses <em>n</em></b> (10)</code>
 376   <dd>The maximum number of dynamic FastCGI application instances allowed to run
 377     for any one FastCGI application.
 378   <dt><code><b>-maxProcesses <em>n</em></b> (50)</code>
 379   <dd>The maximum total number of dynamic FastCGI application instances allowed
 380     to run at any one time.
 381   <dt><code><b>-minProcesses <em>n</em></b> (5)</code>
 382   <dd>The minimum total number of dynamic FastCGI application instances allowed
 383     to run at any one time without being killed off by the process manager (due
 384     to lack of demand).
 385   <dt><code><b>-multiThreshold <em>n</em></b> (50)</code>
 386   <dd>An integer between 0 and 100 used to determine whether any one instance
 387     of a FastCGI application should be terminated. If the application has more
 388     than one instance currently running, this attribute will be used to decide
 389     whether one of them should be terminated. If only one instance remains, <code>singleThreshold</code>
 390     is used instead. <br>
 391     For historic reasons the mis-spelling <code>multiThreshhold</code> is also
 392     accepted.
 393   <dt><code><b>-pass-header <em>header</em></b> (none)</code>
 394   <dd>The name of an HTTP Request Header to be passed in the <i>request</i> environment.
 395     This option makes available the contents of headers which are normally not
 396     available (e.g. Authorization) to a CGI environment.
 397   <dt><code><b>-priority <em>n</em></b> (0)</code>
 398   <dd>The process priority to be assigned to the application instances (using
 399     <code>setpriority()</code>).
 400   <dt><code><b>-processSlack <em>n</em></b> (5)</code>
 401   <dd>If the sum of the number of all currently running dynamic FastCGI applications
 402     and <code>processSlack</code> exceeds <code>maxProcesses</code>, the process
 403     manager invokes the killing policy. This is to improve performance at higher
 404     loads by killing some of the most inactive application instances before reaching
 405     <code>maxProcesses</code>.
 406   <dt><code><b>-restart</b> (none)</code>
 407   <dd>Causes the process manager to restart dynamic applications upon failure
 408     (similar to static applications).
 409   <dt><code><b>-restart-delay <em>n</em></b> (5 seconds)</code>
 410   <dd>The minimum number of seconds between the respawning of failed instances
 411     of applications. This delay prevents a broken application from soaking up
 412     too much of the system.
 413   <dt><code><b>-singleThreshold <em>n</em></b> (0)</code>
 414   <dd>An integer between 0 and 100 used to determine whether the last instance
 415     of a FastCGI application can be terminated. If the process manager computed
 416     load factor for the application is lower than the specified threshold, the
 417     last instance is terminated. In order to make your executables run in the
 418     "idle" mode for the long time, you would specify a value closer to 1, however
 419     if memory or CPU time is of primary concern, a value closer to 100 would be
 420     more applicable. A value of 0 will prevent the last instance of an application
 421     from being terminated; this is the default value, changing it is not recommended
 422     (especially if <code>-appConnTimeout</code> is set). <br>
 423     For historic reasons the mis-spelling <code>singleThreshhold</code> is also
 424     accepted.
 425   <dt><code><b>-startDelay <em>n</em></b> (3 seconds)</code>
 426   <dd>The number of seconds the web server waits patiently while trying to connect
 427     to a dynamic FastCGI application. If the interval expires, the process manager
 428     is notified with hope it will start another instance of the application. The
 429     <code>startDelay</code> must be less than <code>appConnTimeout</code> to be
 430     effective.
 431   <dt><code><b>-updateInterval <em>n</em></b> (300 seconds)</code>
 432   <dd>The updateInterval determines how often statistical analysis is performed
 433     to determine the fate of dynamic FastCGI applications.
 434   <dt>&nbsp;
 435     <hr>
 436     <h2><a name="FastCgiExternalServer">FastCgiExternalServer</a></h2>
 437     <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 438     <table border="0">
 439       <tr>
 440         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 441         <td><code>FastCgiExternalServer <em>filename</em> -host <em>hostname:port
 442           [option ...]</em></code></td>
 443       </tr>
 444       <tr>
 445         <td></td>
 446         <td><code>FastCgiExternalServer <em>filename</em> -socket <em>filename
 447           [option ...]</em></code></td>
 448       </tr>
 449       <tr>
 450         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 451         <td>server config</td>
 452       </tr>
 453     </table>
 454     <p>The <code>FastCgiExternalServer</code> directive defines <em>filename</em>
 455       as an external FastCGI application. If <EM>filename</EM> does not begin
 456       with a slash (/) then it is assumed to be relative to the <a
 457   href="http://www.apache.org/docs/mod/core.html#serverroot">ServerRoot</a>. The
 458       <EM>filename</EM> does not have to exist in the local filesystem. URIs that
 459       Apache resolves to this <EM>filename</EM> will be handled by this external
 460       FastCGI application.. </p>
 461     <p>External FastCGI applications are not started by the process manager, they
 462       are presumed to be started and managed "external" to Apache and mod_fastcgi.
 463       The FastCGI devkit provides a simple tool, <code>cgi-fcgi</code>, for starting
 464       FastCGI applications independent of the server (applications can also be
 465       <i>self-starting</i>, see the devkit).</p>
 466     <p><em>Option</em> can be one of (case insensitive):</p>
 467   <dt><code><b>-appConnTimeout <em>n</em></b> (0 seconds)</code>
 468   <dd><b>Unix:&nbsp</b>The number of seconds to wait for a connection to the FastCGI
 469     application to complete or 0 to indicate a blocking <code>connect()</code>
 470     should be used. Blocking <code>connect()</code>s have an OS dependent internal
 471     timeout. If the timeout expires, a SERVER_ERROR results. For non-zero values,
 472     this is the amount of time used in a <code>select()</code> to write to the
 473     file descriptor returned by a non-blocking <code>connect()</code>. Non-blocking
 474     <code>connect()</code>s are troublesome on many platforms. See also <code>-idle-timeout</code>,
 475     it produces similar results but in a more portable manner.<br>
 476     <b>Windows NT:&nbsp;</b>TCP based applications work as above. Named pipe based
 477     applications (static applications configured without the <code>-port</code>
 478     option and dynamic applications) use this value successfully to limit the
 479     amount of time to wait for a connection (i.e. it's not "troublesome"). By
 480     default, this is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in mod_fastcgi.h).
 481   <dt><code><b>-idle-timeout <em>n</em></b> (30 seconds)</code>
 482   <dd>The number of seconds of FastCGI application inactivity allowed before the
 483     request is aborted and the event is logged (at the <code>error</code> <a href="http://www.apache.org/docs/mod/core.html#loglevel"><code>LogLevel</code></a>).
 484     The inactivity timer applies only as long as a connection is pending with
 485     the FastCGI application. If a request is queued to an application, but the
 486     application doesn't respond (by writing and flushing) within this period,
 487     the request will be aborted. If communication is complete with the application
 488     but incomplete with the client (the response is buffered), the timeout does
 489     not apply.
 490   <dt><code><b>-flush</b> (none)</code>
 491   <dd>Force a write to the client as data is received from the application. By
 492     default, <code>mod_fastcgi</code> buffers data in order to free the application
 493     as quickly as possible.
 494   <dt><code><b>-host <em>hostname:port</em></b> (none)</code>
 495   <dd>The hostname or IP address and TCP port number (1-65535) the application
 496     uses for communication with the web server. The <code>-socket</code> and <code>-host</code>
 497     options are mutually exclusive.
 498   <dt><code><b>-pass-header <em>header</em></b> (none)</code>
 499   <dd>The name of an HTTP Request Header to be passed in the <i>request</i> environment.
 500     This option makes available the contents of headers which are normally not
 501     available (e.g. Authorization) to a CGI environment.
 502   <dt><code><b>-socket<em> filename</em></b> (none)</code>
 503   <dd><b>Unix:&nbsp;</b>The filename of the Unix domain socket the application
 504     uses for communication with the web server. The filename is relative to the
 505     <code><A href="#FastCgiIpcDir">FastCgiIpcDir</A></code>. The <code>-socket</code>
 506     and <code>-port</code> options are mutually exclusive.
 507   <dd> <b>Windows NT:&nbsp;</b> The name of the named pipe the application uses
 508     for communicating with the web server. the name is relative to the <code><A href="#FastCgiIpcDir">
 509     FastCgiIpcDir</A></code>. The <code>-socket</code> and <code>-port</code>
 510     options are mutually exclusive.
 511   <dt>
 512     <hr>
 513     <h2><a name="FastCgiIpcDir">FastCgiIpcDir</a></h2>
 514     <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 515     <table border="0">
 516       <tr>
 517         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 518         <td><code><B>Unix:&nbsp</B>FastCgiIpcDir <em>directory</em></code></td>
 519       </tr>
 520       <tr>
 521         <td></td>
 522         <td><code><b>Windows NT:&nbsp</b>FastCgiIpcDir <i>name</i></code></td>
 523       </tr>
 524       <tr>
 525         <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 526         <td><code><b>Unix:&nbsp;</b>FastCgiIpcDir /tmp/fcgi</code></td>
 527       </tr>
 528       <tr>
 529         <td></td>
 530         <td><code><b>Windows NT:&nbsp;</b>FastCgiIpcDir \\.\pipe\ModFastCgi\</code></td>
 531       </tr>
 532       <tr>
 533         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 534         <td>server config</td>
 535       </tr>
 536     </table>
 537     <p><b>Unix:&nbsp;</b>The <code>FastCgiIpcDir</code> directive specifies <em>directory</em>
 538       as the place to store (and in the case of external FastCGI applications,
 539       find) the Unix socket files used for communication between the applications
 540       and the web server. If the directory does not begin with a slash (/) then
 541       it is assumed to be relative to the <a
 542   href="http://www.apache.org/docs/mod/core.html#serverroot">ServerRoot</a>. If
 543       the directory doesn't exist, an attempt is made to create it with appropriate
 544       permissions. Do not specify a directory that is not on a local filesystem!
 545       If you use the default directory (or another directory within <code>/tmp</code>),
 546       <code>mod_fastcgi</code> will break if your system periodically deletes
 547       files from <code>/tmp</code>.</p>
 548     <p><b>Windows NT:&nbsp;</b>The <code>FastCgiIpcDir </code>directive specifies
 549       <i>name </i>as the root for the named pipes used for communication between
 550       the application and the web server. The <i>name</i> must be in the form
 551       of <b>\\.\pipe\</b><i>pipename. </i>The <i>pipename </i>part can contain
 552       any character other than a backslash</p>
 553     <p>The <code>FastCgiIpcDir</code> directive must precede any <A href="#FastCgiServer"><code>FastCgiServer</code></a>
 554       or <A href="#FastCgiExternalServer"><code>FastCgiExternalServer</code></a>
 555       directives (which make use of Unix sockets). The directory must be readable,
 556       writeable, and executable (searchable) by the web server, but otherwise
 557       should not be accessible to anyone.</p>
 558     <hr>
 559     <h2><a name="FastCgiWrapper">FastCgiWrapper</a></h2>
 560     <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 561     <table border="0">
 562       <tr>
 563         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 564         <td><code>FastCgiWrapper <em>On | Off | filename</em></code></td>
 565       </tr>
 566       <tr>
 567         <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 568         <td><code>FastCgiWrapper Off<em> </em></code></td>
 569       </tr>
 570       <tr>
 571         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 572         <td>server config</td>
 573       </tr>
 574     </table>
 575     <p>The <code>FastCgiWrapper</code> directive is used to enable support for
 576       a wrapper such as <a href="http://httpd.apache.org/docs/suexec.html">suexec</a>
 577       (included with Apache in the support directory) or <a href="http://cgiwrap.sourceforge.net/">cgiwrap</a>.
 578       To use the same wrapper used by Apache, set <code>FastCgiWrapper</code>
 579       to <em>On</em> (NOTE - mod_fastcgi cannot reliably determine the wrapper
 580       used by Apache when built as a DSO). The <i>On</i> argument requires suexec
 581       be enabled in Apache (for CGI). To use a specific wrapper, specify a <em>filename</em>.
 582       If the filename does not begin with a slash (/) then it is assumed to be
 583       relative to the <a
 584
 585   href="http://www.apache.org/docs/mod/core.html#serverroot"
 586  >ServerRoot</a>. The wrapper is used to invoke all FastCGI applications (in the
 587       future this directive will have directory context).</p>
 588     <p>When <code>FastCgiWrapper</code> is enabled, no assumptions are made about
 589       the target application and thus presence and permissions checks cannot be
 590       made. This is the responsibility of the wrapper.</p>
 591     <p>The wrapper is invoked with the following arguments: username, group, application.
 592       The username and group are determined as described below. The application
 593       is the &quot;filename&quot; Apache resolves the requested URI to (dynamic)
 594       or the filename provided as an argument to another FastCGI (server or authorizer)
 595       directive. These arguments may or may not be used by the wrapper (e.g. suexec
 596       uses them, cgiwrap parses the URI and ignores them). The environment passed
 597       to the wrapper is identical to the environment passed when a wrapper is
 598       not in use.</p>
 599     <p>When <code>FastCgiWrapper</code> is enabled, the location of static or
 600       external FastCGI application directives can be important. They inherit their
 601       user and group from the <code>User</code> and <code>Group</code> of the
 602       virtual server in which they were defined. <code>User</code> and <code>Group</code>
 603       directives should precede FastCGI application definitions. Note that this
 604       does <em>not</em> limit the FastCGI application to the virtual server in
 605       which they were defined, the application is allowed to service requests
 606       from any virtual server with the same user and group. If a request is received
 607       for a FastCGI application without an existing matching definition running
 608       with the correct user and group, a dynamic instance of the application is
 609       started with the correct user and group. This can lead to multiple copies
 610       of the same application running with different user/group. If this is a
 611       problem, preclude navigation to the application from other virtual servers
 612       or configure the virtual servers with the same User and Group.</p>
 613     <p>See the Apache documentation for more information about suexec (make sure
 614       you fully understand the security implications).</p>
 615     <hr>
 616     <h2><a name="FastCgiAuthenticator">FastCgiAuthenticator</a></h2>
 617     <!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 618     <table border="0">
 619       <tr>
 620         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 621         <td><code>FastCgiAuthenticator <em>filename</em> [-compat]</code></td>
 622       </tr>
 623       <tr>
 624         <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 625         <td>directory</td>
 626       </tr>
 627     </table>
 628     <p>The <code>FastCgiAuthenticator</code> directive is used to define a FastCGI
 629       application as a per-directory authenticator. Authenticators verify the
 630       requestor is who he says he is by matching the provided username and password
 631       against a list or database of known users and passwords. FastCGI based authenticators
 632       are useful primarily when the user database is maintained within an existing
 633       independent program or resides on a machine other than the web server.</p>
 634     <p>If the FastCGI application <em>filename</em> does not have a corresponding
 635       static or external server definition, it is started as a dynamic FastCGI
 636       application. If the filename does not begin with a slash (/) then it is
 637       assumed to be relative to the <a
 638
 639   href="http://www.apache.org/docs/mod/core.html#serverroot"
 640  >ServerRoot</a>.</p>
 641     <p><code>FastCgiAuthenticator</code> is used within <a
 642   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a>
 643       or <a
 644
 645   href="http://www.apache.org/docs/mod/core.html#location"
 646  ><code>Location</code></a> containers and must include an <a href="http://www.apache.org/docs/mod/core.html#authtype"><code>AuthType</code></a>
 647       and <a href="http://www.apache.org/docs/mod/core.html#authname"><code>AuthName</code></a>
 648       directive. Only the <code>Basic</code> user authentication type is supported.
 649       It must be accompanied by a <a href="http://www.apache.org/docs/mod/core.html#require"><code>require</code></a>
 650       or <code><A href="#FastCgiAuthorizer">FastCgiAuthorizer</a></code> directive
 651       in order to work correctly.</p>
 652 </dl>
 653
 654 <blockquote>
 655   <code><p>&lt;Directory htdocs/protected&gt;<br>
 656   AuthType Basic<br>
 657   AuthName ProtectedRealm<br>
 658   FastCgiAuthenticator fcgi-bin/authenticator<br>
 659   require valid-user<br>
 660   &lt;/Directory&gt;</P></code>
 661 </blockquote>
 662
 663 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 664 typically available to CGI/FastCGI request handlers. All headers returned by a
 665 FastCGI authentication application in a successful response (Status: 200) are passed to
 666 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 667 returned in an unsuccessful response are passed on to the client. FastCGI
 668 specification compliant behavior can be obtained by using the <code>-compat</code>
 669 option.</p>
 670
 671 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 672 "AUTHENTICATOR" to indicate which (Apache specific) authorizer phase is being
 673 performed.</p>
 674
 675 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 676 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 677 directive for a workaround (a FastCGI application can serve the document).</p>
 678
 679 <hr>
 680
 681 <h2><a name="FastCgiAuthenticatorAuthoritative">FastCgiAuthenticatorAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 682
 683 <table border="0">
 684   <tr>
 685     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 686     <td><code>FastCgiAuthenticatorAuthoritative <em>On | Off</em></code></td>
 687   </tr>
 688   <tr>
 689     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 690     <td><code>FastCgiAuthenticatorAuthoritative On</code></td>
 691   </tr>
 692   <tr>
 693     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 694     <td>directory</td>
 695   </tr>
 696 </table>
 697
 698 <p>Setting the <code>FastCgiAuthenticatorAuthoritative</code> directive explicitly to <em>Off</em>
 699 allows authentication to be passed on to lower level modules (as defined in the <code>Configuration</code>
 700 and <code>modules.c</code> files) if the FastCGI application fails to authenticate the
 701 user. </p>
 702
 703 <p>A common use for this is in conjunction with a well protected <a
 704  href="http://www.apache.org/docs/mod/mod_auth.html#authuserfile"><code>AuthUserFile</code></a>
 705 containing a few (administration related) users.</p>
 706
 707 <p>By default, control is not passed on and an unknown user will result in an
 708 Authorization Required reply. Disabling the default should be carefully considered.</p>
 709
 710 <hr>
 711
 712 <h2><a name="FastCgiAuthorizer">FastCgiAuthorizer</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 713
 714 <table border="0">
 715   <tr>
 716     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 717     <td><code>FastCgiAuthorizer <em>filename</em> [-compat]</code></td>
 718   </tr>
 719   <tr>
 720     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 721     <td>directory</td>
 722   </tr>
 723 </table>
 724
 725 <dl>
 726   <p>The <code>FastCgiAuthorizer</code> directive is used to define a FastCGI application as
 727   a per-directory authorizer. Authorizers validate whether an authenticated requestor
 728   is allowed access to the requested resource. FastCGI based authorizers are useful
 729   primarily when there is a dynamic component to the authorization decision such as a time
 730   of day or whether or not the user has paid his bills.</p>
 731   <p>If the FastCGI application <em>filename</em> does not have a corresponding static or
 732   external server definition, it is started as a dynamic FastCGI application. If the
 733   filename does not begin with a slash (/) then it is assumed to be relative to the <a
 734
 735   href="http://www.apache.org/docs/mod/core.html#serverroot"
 736  >ServerRoot</a>.</p>
 737   <p><code>FastCgiAuthorizer</code> is used within <a
 738   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a> or <a
 739
 740   href="http://www.apache.org/docs/mod/core.html#location"
 741  ><code>Location</code></a>
 742   containers and must include an <a href="http://www.apache.org/docs/mod/core.html#authtype"><code>AuthType</code></a>
 743   and <a href="http://www.apache.org/docs/mod/core.html#authname"><code>AuthName</code></a>
 744   directive. It must be accompanied by an authentication directive such as <A
 745   href="#FastCgiAuthenticator"><code>FastCgiAuthenticator</code></a>, <a
 746
 747   href="http://www.apache.org/docs/mod/mod_auth.html#authuserfile"
 748  ><code>AuthUserFile</code></a>,
 749   <a href="http://www.apache.org/docs/mod/mod_auth_db.html#authdbuserfile"><code>AuthDBUserFile</code></a>
 750   or <a href="http://www.apache.org/docs/mod/mod_auth_dbm.html#authdbmuserfile"><code>AuthDBMUserFile</code></a>
 751   in order to work correctly.</p>
 752 </dl>
 753
 754 <blockquote>
 755   <code><p>&lt;Directory htdocs/protected&gt;<br>
 756   AuthType Basic<br>
 757   AuthName ProtectedRealm<br>
 758   AuthDBMUserFile conf/authentication-database<br>
 759   FastCgiAuthorizer fcgi-bin/authorizer<br>
 760   &lt;/Directory&gt;</P></code>
 761 </blockquote>
 762
 763 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 764 typically available to CGI/FastCGI request handlers. All headers returned by a
 765 FastCGI authorizer application in a successful response (Status: 200) are passed to
 766 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 767 returned in an unsuccessful response are passed on to the client. FastCGI
 768 specification compliant behavior can be obtained by using the <code>-compat</code>
 769 option.</p>
 770
 771 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 772 "AUTHORIZER" to indicate which (Apache specific) authorizer phase is being
 773 performed.</p>
 774
 775 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 776 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 777 directive for a workaround (a FastCGI application can serve the document).</p>
 778
 779 <hr>
 780
 781 <h2><a name="FastCgiAuthorizerAuthoritative">FastCgiAuthorizerAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 782
 783 <table border="0">
 784   <tr>
 785     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 786     <td><code>FastCgiAuthorizerAuthoritative <em>On | Off</em></code></td>
 787   </tr>
 788   <tr>
 789     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 790     <td><code>FastCgiAuthorizerAuthoritative On</code></td>
 791   </tr>
 792   <tr>
 793     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 794     <td>directory</td>
 795   </tr>
 796 </table>
 797
 798 <p>Setting the <code>FastCgiAuthorizerAuthoritative</code> directive explicitly to <em>Off</em>
 799 allows authorization to be passed on to lower level modules (as defined in the <code>Configuration</code>
 800 and <code>modules.c</code> files) if the FastCGI application fails to authorize the user. </p>
 801
 802 <p>By default, control is not passed on and an unauthorized user will result in an
 803 Authorization Required reply. Disabling the default should be carefully considered.</p>
 804
 805 <hr>
 806
 807 <h2><a name="FastCgiAccessChecker">FastCgiAccessChecker</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 808
 809 <table border="0">
 810   <tr>
 811     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 812     <td><code>FastCgiAccessChecker <em>filename</em> [-compat]</code></td>
 813   </tr>
 814   <tr>
 815     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 816     <td>directory</td>
 817   </tr>
 818 </table>
 819
 820 <dl>
 821   <p>The <code>FastCgiAccessChecker</code> (suggestions for a better name are welcome)
 822   directive is used to define a FastCGI application as a per-directory access
 823   validator. The Apache Access phase precede user authentication and thus the decision
 824   to (dis)allow access to the requested resource is based on the HTTP headers submitted with
 825   the request. FastCGI based authorizers are useful primarily when there is a dynamic
 826   component to the access validation decision such as a time of day or whether or not a
 827   domain has paid his bills.</p>
 828   <p>If the FastCGI application <em>filename</em> does not have a corresponding static or
 829   external server definition, it is started as a dynamic FastCGI application. If the
 830   filename does not begin with a slash (/) then it is assumed to be relative to the <a
 831
 832   href="http://www.apache.org/docs/mod/core.html#serverroot"
 833  >ServerRoot</a>.</p>
 834   <p><code>FastCgiAccessChecker</code> is used within <a
 835   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a> or <a
 836
 837   href="http://www.apache.org/docs/mod/core.html#location"
 838  ><code>Location</code></a>
 839   containers.</p>
 840 </dl>
 841
 842 <blockquote>
 843   <code><p>&lt;Directory htdocs/protected&gt;<br>
 844   FastCgiAccessChecker fcgi-bin/access-checker<br>
 845   &lt;/Directory&gt;</P></code>
 846 </blockquote>
 847
 848 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 849 typically available to CGI/FastCGI request handlers. All headers returned by a
 850 FastCGI access-checker application in a successful response (Status: 200) are passed to
 851 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 852 returned in an unsuccessful response are passed on to the client. FastCGI
 853 specification compliant behavior can be obtained by using the <code>-compat</code>
 854 option.</p>
 855
 856 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 857 "ACCESS_CHECKER" to indicate which (Apache specific) authorizer phase is being
 858 performed.</p>
 859
 860 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 861 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 862 directive for a workaround (a FastCGI application can serve the document).</p>
 863
 864 <hr>
 865
 866 <h2><a name="FastCgiAccessCheckerAuthoritative">FastCgiAccessCheckerAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 867
 868 <table border="0">
 869   <tr>
 870     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 871     <td><code>FastCgiAccessCheckerAuthoritative <em>On | Off</em></code></td>
 872   </tr>
 873   <tr>
 874     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 875     <td><code>FastCgiAccessCheckerAuthoritative On</code></td>
 876   </tr>
 877   <tr>
 878     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 879     <td>directory</td>
 880   </tr>
 881 </table>
 882
 883 <p>Setting the <code>FastCgiAccessCheckerAuthoritative</code> directive explicitly to <em>Off</em>
 884 allows access checking to be passed on to lower level modules (as defined in the <code>Configuration</code>
 885 and <code>modules.c</code> files) if the FastCGI application fails to allow access. </p>
 886
 887 <p>By default, control is not passed on and a failed access check will result in a
 888 Forbidden reply. Disabling the default should be carefully considered.</p>
 889
 890 <hr>
 891
 892 <h3 ALIGN="center"><a href="http://www.FastCGI.com/">www.FastCGI.com</a></h3>
 893 </body>
 894 </html>