docs/mod_fastcgi.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2 <html>
   3 <!-- $Id: mod_fastcgi.html,v 1.21 2001/02/19 06:21:17 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</a></code>
 168     <li><A href="#FastCgiExternalServer"><code>FastCgiExternalServer</code></a>
 169     <li><A href="#FastCgiIpcDir"><code>FastCgiIpcDir</a></code>
 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><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 300   <table border="0">
 301     <tr>
 302       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 303       <td><code>FastCgiConfig <em>option [option ...]</em></code></td>
 304     </tr>
 305     <tr>
 306       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 307       <td>server config</td>
 308     </tr>
 309   </table>
 310   <p>The <code>FastCgiConfig</code> directive defines the default parameters for
 311   <i>all</i> dynamic
 312   FastCGI applications. This directive does not affect static or external
 313   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 demand
 316   fades, application instances are killed off. Many of the options govern this
 317   process.</p>
 318   <p><em>Option</em> can be one of (case insensitive):</p>
 319
 320   <dt><code><b>-appConnTimeout <em>n</em></b> (0 seconds)</code>
 321   <dd><b>Unix:&nbsp;</b>The number of seconds to wait for a connection to the FastCGI application to
 322     complete or 0 to indicate a blocking <code>connect()</code> should be
 323     used. Blocking <code>connect()</code>s have an OS dependent internal
 324     timeout. If the timeout expires, a SERVER_ERROR results. For
 325     non-zero values, this is the amount of time used in a <code>select()</code>
 326     to write to the file descriptor returned by a non-blocking
 327     <code>connect()</code>. Non-blocking <code>connect()</code>s are troublesome
 328     on many platforms. See also <code>-idle-timeout</code>, it produces similar results
 329     but in a more portable manner.<br>
 330  <b>Windows NT:&nbsp;</b>TCP based applications work as above. Named pipe based
 331   applications (static applications configured without the <code>-port</code> option and
 332   dynamic applications) use this value successfully to limit the amount of time
 333   to wait for a connection (i.e. it's not "troublesome"). By default, this
 334   is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in mod_fastcgi.h).
 335
 336   <dt><code><b>-autoUpdate</b> (none)</code>
 337   <dd>Causes mod_fastcgi to check the modification time of the application on disk before
 338     processing each request. If the application on disk has been changed, the process manager is
 339     notified and all running instances of the application are killed off. In general,
 340     it's preferred that this type of functionality be built-in to the application (e.g. every
 341     100th request it checks to see if there's a newer version on disk and exits if so).
 342     There may be an outstanding problem (bug) when this option is used with <code>-restart</code>.
 343
 344   <dt><code><b>-gainValue <em>n</em></b> (0.5)</code>
 345   <dd>A floating point value between 0 and 1 used as an exponent in the computation of
 346     the exponentially decayed connection times load factor of the currently running dynamic
 347     FastCGI applications. Old values are scaled by (<code>1&nbsp;-&nbsp;gainValue</code>), so
 348     making it smaller weights old values more than the current value (which is scaled
 349     by <code>gainValue</code>).
 350
 351   <dt><code><b>-idle-timeout <em>n</em></b> (30 seconds)</code>
 352   <dd>The number of seconds of FastCGI application inactivity allowed before the
 353     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>).
 354   The inactivity timer applies only as long as a connection is pending with the
 355   FastCGI application. If a request is queued to an application, but the
 356   application doesn't respond (by writing and flushing) within this period, the
 357   request will be aborted. If communication is complete with the
 358   application but incomplete with the client (the response is buffered), the
 359   timeout does not apply.
 360
 361   <dt><code><b>-initial-env <em>name[=[value]]</EM></b> (none)</code>
 362   <dd>A name-value pair to be passed in the initial
 363   environment when instances of applications are spawned. To pass a
 364   variable from the Apache environment, don't provide the "=" (if the variable
 365   isn't actually in the environment, it will be defined without a value).
 366   To define a variable without a value, provide the "=" without any value.
 367   The option can be used repeatedly.
 368
 369   <dt><code><b>-init-start-delay <em>n</em></b> (1 second)</code>
 370   <dd>The minimum number of seconds between the spawning of
 371   instances of applications. This delay decreases the demand placed
 372   on the system at server initialization.
 373
 374   <dt><code><b>-killInterval <em>n</em></b> (300 seconds)</code>
 375   <dd>Determines how often the dynamic
 376   application instance killing policy is implemented within the process
 377   manager. Smaller numbers result in a more aggressive policy, larger
 378   numbers a less aggressive policy.
 379
 380   <dt><code><b>-listen-queue-depth <em>n</em></b> (100)</code>
 381   <dd>The depth of <code>listen()</code> queue (also known as the
 382   backlog) shared by all instances of applications. A deeper
 383   listen queue allows the server to cope with transient load fluctuations
 384   without rejecting requests; it does not increase throughput. Adding
 385   additional application instances may increase throughput/performance,
 386   depending upon the application and the host.
 387
 388   <dt><code><b>-maxClassProcesses <em>n</em></b> (10)</code>
 389   <dd>The maximum number of dynamic FastCGI application
 390   instances allowed to run for any one FastCGI application.
 391
 392   <dt><code><b>-maxProcesses <em>n</em></b> (50)</code>
 393   <dd>The maximum total number of dynamic FastCGI
 394   application instances allowed to run at any one time.
 395
 396   <dt><code><b>-minProcesses <em>n</em></b> (5)</code>
 397   <dd>The minimum total number of dynamic FastCGI
 398   application instances allowed to run at any one time without being killed off
 399   by the process manager (due to lack of demand).
 400
 401   <dt><code><b>-multiThreshold <em>n</em></b> (50)</code>
 402   <dd>An integer between 0 and 100 used to determine whether any one instance of a FastCGI
 403     application should be terminated. If the application has more than one instance
 404     currently running, this attribute will be used to decide whether one of them should be
 405     terminated. If only one instance remains, <code>singleThreshold</code> is used instead.
 406   <br>For historic reasons the mis-spelling <code>multiThreshhold</code> is also accepted.
 407
 408   <dt><code><b>-pass-header <em>header</em></b> (none)</code>
 409   <dd>The name of an HTTP Request Header to be passed in the <i>request</i> environment. This option makes
 410   available the contents of headers which are normally not available (e.g.
 411   Authorization) to a CGI environment.
 412
 413   <dt><code><b>-priority <em>n</em></b> (0)</code>
 414   <dd>The process priority to be assigned to the application instances (using <code>setpriority()</code>).
 415
 416   <dt><code><b>-processSlack <em>n</em></b> (5)</code>
 417   <dd>If the sum of the number of all currently running dynamic FastCGI
 418   applications and <code>processSlack</code> exceeds <code>maxProcesses</code>,
 419   the process manager invokes the killing policy. This is to improve
 420   performance at higher loads by killing some of the most inactive application
 421   instances before reaching <code>maxProcesses</code>.
 422
 423   <dt><code><b>-restart</b> (none)</code>
 424   <dd>Causes the process manager to restart
 425   dynamic applications upon failure (similar to static applications).
 426
 427   <dt><code><b>-restart-delay <em>n</em></b> (5 seconds)</code>
 428   <dd>The minimum number of seconds between the respawning
 429   of failed instances of applications. This delay prevents a broken
 430   application from soaking up too much of the system.
 431
 432   <dt><code><b>-singleThreshold <em>n</em></b> (0)</code>
 433   <dd>An integer between 0 and 100 used to determine
 434   whether the last instance of a FastCGI application can be terminated. If
 435   the process manager computed load factor for the application is lower than the
 436   specified threshold, the last instance is terminated. In order to make
 437   your executables run in the "idle" mode for the long time, you would specify
 438   a value closer to 1, however if memory or CPU time is of primary concern, a
 439   value closer to 100 would be more applicable. A value of 0 will prevent
 440   the last instance of an application from being terminated; this is the default
 441   value, changing it is not recommended (especially if <code>-appConnTimeout</code> is set).
 442   <br>For historic reasons the mis-spelling <code>singleThreshhold</code> is also accepted.
 443
 444   <dt><code><b>-startDelay <em>n</em></b> (3 seconds)</code>
 445   <dd>The number of seconds the web server waits patiently while trying to connect to a
 446     dynamic FastCGI application. If the interval expires, the process manager is
 447     notified with hope it will start another instance of the application. The <code>startDelay</code>
 448     must be less than <code>appConnTimeout</code> to be effective.
 449   <dt><code><b>-updateInterval <em>n</em></b> (300 seconds)</code>
 450   <dd>The updateInterval determines how often statistical
 451   analysis is performed to determine the fate of dynamic FastCGI applications.
 452
 453   <dt>&nbsp;
 454   <hr>
 455   <h2><a name="FastCgiExternalServer">FastCgiExternalServer</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 456   <table border="0">
 457     <tr>
 458       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 459       <td><code>FastCgiExternalServer <em>filename</em> -host <em>hostname:port
 460         [option ...]</em></code></td>
 461     </tr>
 462     <tr>
 463       <td></td>
 464       <td><code>FastCgiExternalServer <em>filename</em> -socket <em>filename [option ...]</em></code></td>
 465     </tr>
 466     <tr>
 467       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 468       <td>server config</td>
 469     </tr>
 470   </table>
 471   <p>The <code>FastCgiExternalServer</code> directive defines <em>filename</em> as an external FastCGI application.
 472   If <EM>filename</EM>
 473         does not begin with a slash (/) then
 474   it is assumed to be relative to the <a
 475   href="http://www.apache.org/docs/mod/core.html#serverroot">ServerRoot</a>. The <EM>filename</EM> does
 476   not have to exist in the local filesystem. URIs that Apache
 477   resolves to this <EM>filename</EM> will be handled by this external
 478   FastCGI application.. </p>
 479   <p>External FastCGI applications are not started by the process manager, they are presumed
 480   to be started and managed "external" to Apache and mod_fastcgi. The
 481   FastCGI devkit provides a simple tool, <code>cgi-fcgi</code>, for starting FastCGI applications independent of the
 482   server (applications can also be <i>self-starting</i>, see the devkit).</p>
 483   <p><em>Option</em> can be one of (case insensitive):</p>
 484
 485   <dt><code><b>-appConnTimeout <em>n</em></b> (0 seconds)</code>
 486   <dd><b>Unix:&nbsp</b>The number of seconds to wait for a connection to the FastCGI application to
 487     complete or 0 to indicate a blocking <code>connect()</code> should be
 488     used. Blocking <code>connect()</code>s have an OS dependent internal
 489     timeout. If the timeout expires, a SERVER_ERROR results. For
 490     non-zero values, this is the amount of time used in a <code>select()</code>
 491     to write to the file descriptor returned by a non-blocking
 492     <code>connect()</code>. Non-blocking <code>connect()</code>s are troublesome
 493     on many platforms. See also <code>-idle-timeout</code>, it produces similar results
 494     but in a more portable manner.<br>
 495  <b>Windows NT:&nbsp;</b>TCP based applications work as above. Named pipe based
 496   applications (static applications configured without the <code>-port</code> option and
 497   dynamic applications) use this value successfully to limit the amount of time
 498   to wait for a connection (i.e. it's not "troublesome"). By default, this
 499   is 90 seconds (FCGI_NAMED_PIPE_CONNECT_TIMEOUT in mod_fastcgi.h).
 500
 501   <dt><code><b>-idle-timeout <em>n</em></b> (30 seconds)</code>
 502   <dd>The number of seconds of FastCGI application inactivity allowed before the
 503     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>).
 504   The inactivity timer applies only as long as a connection is pending with the
 505   FastCGI application. If a request is queued to an application, but the
 506   application doesn't respond (by writing and flushing) within this period, the
 507   request will be aborted. If communication is complete with the
 508   application but incomplete with the client (the response is buffered), the
 509   timeout does not apply.
 510
 511   <dt><code><b>-flush</b> (none)</code>
 512   <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
 513   application as quickly as possible.
 514
 515   <dt><code><b>-host <em>hostname:port</em></b> (none)</code>
 516   <dd>The hostname or IP address and TCP port number (1-65535) the application uses for
 517     communication with the web server. The <code>-socket</code> and <code>-host</code> options are mutually exclusive.
 518
 519   <dt><code><b>-pass-header <em>header</em></b> (none)</code>
 520   <dd>The name of an HTTP Request Header to be passed in the <i>request</i> environment. This option makes
 521   available the contents of headers which are normally not available (e.g.
 522   Authorization) to a CGI environment.
 523
 524   <dt><code><b>-socket<em> filename</em></b> (none)</code>
 525   <dd><b>Unix:&nbsp;</b>The filename of the Unix domain socket the application uses for communication with the
 526     web server. The filename is relative to the <code><A href="#FastCgiIpcDir">FastCgiIpcDir</A></code>. The <code>-socket</code>
 527     and <code>-port</code> options are mutually exclusive.
 528   <dd> <b>Windows NT:&nbsp;</b> The name of the named pipe the application uses
 529 for communicating with the web server. the name is relative to the <code><A href="#FastCgiIpcDir">
 530 FastCgiIpcDir</A></code>.
 531 The <code>-socket</code> and <code>-port</code> options are mutually exclusive.
 532   <dt>
 533   <hr>
 534   <h2><a name="FastCgiIpcDir">FastCgiIpcDir</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 535   <table border="0">
 536     <tr>
 537       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 538       <td><code><B>Unix:&nbsp</B>FastCgiIpcDir <em>directory</em></code></td>
 539     </tr>
 540     <tr>
 541        <td></td>
 542        <td><code><b>Windows NT:&nbsp</b>FastCgiIpcDir <i>name</i></code></td>
 543     </tr>
 544     <tr>
 545       <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 546       <td><code><b>Unix:&nbsp;</b>FastCgiIpcDir /tmp/fcgi</code></td>
 547     </tr>
 548     <tr>
 549       <td></td>
 550       <td><code><b>Windows NT:&nbsp;</b>FastCgiIpcDir \\.\pipe\ModFastCgi\</code></td>
 551     </tr>
 552     <tr>
 553       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 554       <td>server config</td>
 555     </tr>
 556   </table>
 557   <p><b>Unix:&nbsp;</b>The <code>FastCgiIpcDir</code> directive specifies <em>directory</em> as the place to
 558   store (and in the case of external FastCGI applications, find) the Unix socket files used
 559   for communication between the applications and the web server. If the directory does
 560   not begin with a slash (/) then it is assumed to be relative to the <a
 561   href="http://www.apache.org/docs/mod/core.html#serverroot">ServerRoot</a>. If the
 562   directory doesn't exist, an attempt is made to create it with appropriate
 563   permissions. Do not specify a directory that is not on a local filesystem! If
 564   you use the default directory (or another directory within <code>/tmp</code>), <code>mod_fastcgi</code>
 565   will break if your system periodically deletes files from <code>/tmp</code>.</p>
 566   <p><b>Windows NT:&nbsp;</b>The <code>FastCgiIpcDir </code>directive specifies <i>name
 567   </i>as the root for the named pipes used for communication between the
 568   application and the web server. The <i>name</i> must be in the form
 569   of <b>\\.\pipe\</b><i>pipename. </i>The <i>pipename </i>part can contain
 570   any character other than a backslash</p>
 571   <p>The <code>FastCgiIpcDir</code> directive must precede any <A href="#FastCgiServer"><code>FastCgiServer</code></a>
 572   or <A href="#FastCgiExternalServer"><code>FastCgiExternalServer</code></a> directives
 573   (which make use of Unix sockets). The directory must be readable, writeable, and
 574   executable (searchable) by the web server, but otherwise should not be accessible to
 575   anyone.</p>
 576   <hr>
 577   <h2><a name="FastCgiWrapper">FastCgiWrapper</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 578   <table border="0">
 579     <tr>
 580       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 581       <td><code>FastCgiWrapper <em>On | Off | filename</em></code></td>
 582     </tr>
 583     <tr>
 584       <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 585       <td><code>FastCgiWrapper Off<em> </em></code></td>
 586     </tr>
 587     <tr>
 588       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 589       <td>server config</td>
 590     </tr>
 591   </table>
 592   <p>The <code>FastCgiWrapper</code> directive is used to enable support for a
 593   wrapper such as suexec or cgiwrap. To use the same wrapper used by Apache, set <code>FastCgiWrapper</code>
 594   to <em>On</em> (NOTE - mod_fastcgi cannot reliably determine the wrapper
 595   used by Apache when built as a DSO). The <i>On</i> argument requires suexec be enabled in Apache (for
 596   CGI). To use a specific wrapper, specify
 597   a <em>filename</em>. If the filename does not begin with a slash (/) then it is
 598   assumed to be relative to the <a
 599
 600   href="http://www.apache.org/docs/mod/core.html#serverroot"
 601  >ServerRoot</a>. The wrapper is used to invoke all FastCGI applications
 602   (in the future this directive will have directory context).</p>
 603   <p>When <code>FastCgiWrapper</code> is enabled, no assumptions are made about
 604   the target application and thus presence and permissions checks cannot be
 605   made. This is the responsibility of the wrapper.</p>
 606   <p>The wrapper is invoked with the following arguments: username, group,
 607   application. The username and group are determined as described
 608   below. The application is the &quot;filename&quot; Apache resolves the
 609   requested URI to (dynamic) or the filename provided as an argument to another
 610   FastCGI (server or authorizer) directive. These arguments may or may not
 611   be used by the wrapper (e.g. suexec uses them, cgiwrap parses the URI and
 612   ignores them). The environment passed to the wrapper is identical to the
 613   environment passed when a wrapper is not in use.</p>
 614   <p>When <code>FastCgiWrapper</code> is enabled, the location of static or external FastCGI
 615   application directives can be important. They inherit their user and group from the <code>User</code>
 616   and <code>Group</code> of the virtual server in which they were defined. <code>User</code>
 617   and <code>Group</code> directives should precede FastCGI application definitions.
 618   Note that this does <em>not</em> limit the FastCGI application to the virtual server in
 619   which they were defined, the application is allowed to service requests from any virtual
 620   server with the same user and group. If a request is received for a FastCGI
 621   application without an existing matching definition running with the correct user and
 622   group, a dynamic instance of the application is started with the correct user and group.
 623   This can lead to multiple copies of the same application running with different
 624   user/group. If this is a problem, preclude navigation to the application from other
 625   virtual servers or configure the virtual servers with the same User and Group.</p>
 626   <p>See the Apache documentation for more information about suexec (make sure you fully
 627   understand the security implications).</p>
 628   <hr>
 629   <h2><a name="FastCgiAuthenticator">FastCgiAuthenticator</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 630   <table border="0">
 631     <tr>
 632       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 633       <td><code>FastCgiAuthenticator <em>filename</em> [-compat]</code></td>
 634     </tr>
 635     <tr>
 636       <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 637       <td>directory</td>
 638     </tr>
 639   </table>
 640   <p>The <code>FastCgiAuthenticator</code> directive is used to define a FastCGI application
 641   as a per-directory authenticator. Authenticators verify the requestor is who he says
 642   he is by matching the provided username and password against a list or database of known
 643   users and passwords. FastCGI based authenticators are useful primarily when the user
 644   database is maintained within an existing independent program or resides on a machine
 645   other than the web server.</p>
 646   <p>If the FastCGI application <em>filename</em> does not have a corresponding static or
 647   external server definition, it is started as a dynamic FastCGI application. If the
 648   filename does not begin with a slash (/) then it is assumed to be relative to the <a
 649
 650   href="http://www.apache.org/docs/mod/core.html#serverroot"
 651  >ServerRoot</a>.</p>
 652   <p><code>FastCgiAuthenticator</code> is used within <a
 653   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a> or <a
 654
 655   href="http://www.apache.org/docs/mod/core.html#location"
 656  ><code>Location</code></a>
 657   containers and must include an <a href="http://www.apache.org/docs/mod/core.html#authtype"><code>AuthType</code></a>
 658   and <a href="http://www.apache.org/docs/mod/core.html#authname"><code>AuthName</code></a>
 659   directive. Only the <code>Basic</code> user authentication type is supported.
 660   It must be accompanied by a <a href="http://www.apache.org/docs/mod/core.html#require"><code>require</code></a>
 661   or <code><A href="#FastCgiAuthorizer">FastCgiAuthorizer</a></code> directive in order to
 662   work correctly.</p>
 663 </dl>
 664
 665 <blockquote>
 666   <code><p>&lt;Directory htdocs/protected&gt;<br>
 667   AuthType Basic<br>
 668   AuthName ProtectedRealm<br>
 669   FastCgiAuthenticator fcgi-bin/authenticator<br>
 670   require valid-user<br>
 671   &lt;/Directory&gt;</code></P>
 672 </blockquote>
 673
 674 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 675 typically available to CGI/FastCGI request handlers. All headers returned by a
 676 FastCGI authentication application in a successful response (Status: 200) are passed to
 677 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 678 returned in an unsuccessful response are passed on to the client. FastCGI
 679 specification compliant behavior can be obtained by using the <code>-compat</code>
 680 option.</p>
 681
 682 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 683 "AUTHENTICATOR" to indicate which (Apache specific) authorizer phase is being
 684 performed.</p>
 685
 686 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 687 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 688 directive for a workaround (a FastCGI application can serve the document).</p>
 689
 690 <hr>
 691
 692 <h2><a name="FastCgiAuthenticatorAuthoritative">FastCgiAuthenticatorAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 693
 694 <table border="0">
 695   <tr>
 696     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 697     <td><code>FastCgiAuthenticatorAuthoritative <em>On | Off</em></code></td>
 698   </tr>
 699   <tr>
 700     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 701     <td><code>FastCgiAuthenticatorAuthoritative On</code></td>
 702   </tr>
 703   <tr>
 704     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 705     <td>directory</td>
 706   </tr>
 707 </table>
 708
 709 <p>Setting the <code>FastCgiAuthenticatorAuthoritative</code> directive explicitly to <em>Off</em>
 710 allows authentication to be passed on to lower level modules (as defined in the <code>Configuration</code>
 711 and <code>modules.c</code> files) if the FastCGI application fails to authenticate the
 712 user. </p>
 713
 714 <p>A common use for this is in conjunction with a well protected <a
 715  href="http://www.apache.org/docs/mod/mod_auth.html#authuserfile"><code>AuthUserFile</code></a>
 716 containing a few (administration related) users.</p>
 717
 718 <p>By default, control is not passed on and an unknown user will result in an
 719 Authorization Required reply. Disabling the default should be carefully considered.</p>
 720
 721 <hr>
 722
 723 <h2><a name="FastCgiAuthorizer">FastCgiAuthorizer</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 724
 725 <table border="0">
 726   <tr>
 727     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 728     <td><code>FastCgiAuthorizer <em>filename</em> [-compat]</code></td>
 729   </tr>
 730   <tr>
 731     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 732     <td>directory</td>
 733   </tr>
 734 </table>
 735
 736 <dl>
 737   <p>The <code>FastCgiAuthorizer</code> directive is used to define a FastCGI application as
 738   a per-directory authorizer. Authorizers validate whether an authenticated requestor
 739   is allowed access to the requested resource. FastCGI based authorizers are useful
 740   primarily when there is a dynamic component to the authorization decision such as a time
 741   of day or whether or not the user has paid his bills.</p>
 742   <p>If the FastCGI application <em>filename</em> does not have a corresponding static or
 743   external server definition, it is started as a dynamic FastCGI application. If the
 744   filename does not begin with a slash (/) then it is assumed to be relative to the <a
 745
 746   href="http://www.apache.org/docs/mod/core.html#serverroot"
 747  >ServerRoot</a>.</p>
 748   <p><code>FastCgiAuthorizer</code> is used within <a
 749   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a> or <a
 750
 751   href="http://www.apache.org/docs/mod/core.html#location"
 752  ><code>Location</code></a>
 753   containers and must include an <a href="http://www.apache.org/docs/mod/core.html#authtype"><code>AuthType</code></a>
 754   and <a href="http://www.apache.org/docs/mod/core.html#authname"><code>AuthName</code></a>
 755   directive. It must be accompanied by an authentication directive such as <A
 756   href="#FastCgiAuthenticator"><code>FastCgiAuthenticator</code></a>, <a
 757
 758   href="http://www.apache.org/docs/mod/mod_auth.html#authuserfile"
 759  ><code>AuthUserFile</code></a>,
 760   <a href="http://www.apache.org/docs/mod/mod_auth_db.html#authdbuserfile"><code>AuthDBUserFile</code></a>
 761   or <a href="http://www.apache.org/docs/mod/mod_auth_dbm.html#authdbmuserfile"><code>AuthDBMUserFile</code></a>
 762   in order to work correctly.</p>
 763 </dl>
 764
 765 <blockquote>
 766   <code><p>&lt;Directory htdocs/protected&gt;<br>
 767   AuthType Basic<br>
 768   AuthName ProtectedRealm<br>
 769   AuthDBMUserFile conf/authentication-database<br>
 770   FastCgiAuthorizer fcgi-bin/authorizer<br>
 771   &lt;/Directory&gt;</code></P>
 772 </blockquote>
 773
 774 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 775 typically available to CGI/FastCGI request handlers. All headers returned by a
 776 FastCGI authorizer application in a successful response (Status: 200) are passed to
 777 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 778 returned in an unsuccessful response are passed on to the client. FastCGI
 779 specification compliant behavior can be obtained by using the <code>-compat</code>
 780 option.</p>
 781
 782 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 783 "AUTHORIZER" to indicate which (Apache specific) authorizer phase is being
 784 performed.</p>
 785
 786 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 787 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 788 directive for a workaround (a FastCGI application can serve the document).</p>
 789
 790 <hr>
 791
 792 <h2><a name="FastCgiAuthorizerAuthoritative">FastCgiAuthorizerAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 793
 794 <table border="0">
 795   <tr>
 796     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 797     <td><code>FastCgiAuthorizerAuthoritative <em>On | Off</em></code></td>
 798   </tr>
 799   <tr>
 800     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 801     <td><code>FastCgiAuthorizerAuthoritative On</code></td>
 802   </tr>
 803   <tr>
 804     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 805     <td>directory</td>
 806   </tr>
 807 </table>
 808
 809 <p>Setting the <code>FastCgiAuthorizerAuthoritative</code> directive explicitly to <em>Off</em>
 810 allows authorization to be passed on to lower level modules (as defined in the <code>Configuration</code>
 811 and <code>modules.c</code> files) if the FastCGI application fails to authorize the user. </p>
 812
 813 <p>By default, control is not passed on and an unauthorized user will result in an
 814 Authorization Required reply. Disabling the default should be carefully considered.</p>
 815
 816 <hr>
 817
 818 <h2><a name="FastCgiAccessChecker">FastCgiAccessChecker</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 819
 820 <table border="0">
 821   <tr>
 822     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 823     <td><code>FastCgiAccessChecker <em>filename</em> [-compat]</code></td>
 824   </tr>
 825   <tr>
 826     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 827     <td>directory</td>
 828   </tr>
 829 </table>
 830
 831 <dl>
 832   <p>The <code>FastCgiAccessChecker</code> (suggestions for a better name are welcome)
 833   directive is used to define a FastCGI application as a per-directory access
 834   validator. The Apache Access phase precede user authentication and thus the decision
 835   to (dis)allow access to the requested resource is based on the HTTP headers submitted with
 836   the request. FastCGI based authorizers are useful primarily when there is a dynamic
 837   component to the access validation decision such as a time of day or whether or not a
 838   domain has paid his bills.</p>
 839   <p>If the FastCGI application <em>filename</em> does not have a corresponding static or
 840   external server definition, it is started as a dynamic FastCGI application. If the
 841   filename does not begin with a slash (/) then it is assumed to be relative to the <a
 842
 843   href="http://www.apache.org/docs/mod/core.html#serverroot"
 844  >ServerRoot</a>.</p>
 845   <p><code>FastCgiAccessChecker</code> is used within <a
 846   href="http://www.apache.org/docs/mod/core.html#directory"><code>Directory</code></a> or <a
 847
 848   href="http://www.apache.org/docs/mod/core.html#location"
 849  ><code>Location</code></a>
 850   containers.</p>
 851 </dl>
 852
 853 <blockquote>
 854   <code><p>&lt;Directory htdocs/protected&gt;<br>
 855   FastCgiAccessChecker fcgi-bin/access-checker<br>
 856   &lt;/Directory&gt;</code></P>
 857 </blockquote>
 858
 859 <p><code>mod_fastcgi</code> sends nearly all of the standard environment variables
 860 typically available to CGI/FastCGI request handlers. All headers returned by a
 861 FastCGI access-checker application in a successful response (Status: 200) are passed to
 862 sub-processes (CGI/FastCGI invocations) as environment variables. All headers
 863 returned in an unsuccessful response are passed on to the client. FastCGI
 864 specification compliant behavior can be obtained by using the <code>-compat</code>
 865 option.</p>
 866
 867 <p><code>mod_fastcgi</code> sets the environment variable "FCGI_APACHE_ROLE" to
 868 "ACCESS_CHECKER" to indicate which (Apache specific) authorizer phase is being
 869 performed.</p>
 870
 871 <p>Custom failure responses from FastCGI authorizer applications are not (yet?)
 872 supported. See the <a href="http://www.apache.org/docs/mod/core.html#errordocument">ErrorDocument</a>
 873 directive for a workaround (a FastCGI application can serve the document).</p>
 874
 875 <hr>
 876
 877 <h2><a name="FastCgiAccessCheckerAuthoritative">FastCgiAccessCheckerAuthoritative</a></h2><!-- %plaintext &lt;?INDEX {\tt FastCgiConfig} directive&gt; -->
 878
 879 <table border="0">
 880   <tr>
 881     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Syntax" REL="Help"><strong>Syntax:</strong></a></td>
 882     <td><code>FastCgiAccessCheckerAuthoritative <em>On | Off</em></code></td>
 883   </tr>
 884   <tr>
 885     <td><a href="http://www.apache.org/docs/mod/directive-dict.html#Default"><strong>Default:</strong></a></td>
 886     <td><code>FastCgiAccessCheckerAuthoritative On</code></td>
 887   </tr>
 888   <tr>
 889     <td><a HREF="http://www.apache.org/docs/mod/directive-dict.html#Context" REL="Help"><strong>Context:</strong></a></td>
 890     <td>directory</td>
 891   </tr>
 892 </table>
 893
 894 <p>Setting the <code>FastCgiAccessCheckerAuthoritative</code> directive explicitly to <em>Off</em>
 895 allows access checking to be passed on to lower level modules (as defined in the <code>Configuration</code>
 896 and <code>modules.c</code> files) if the FastCGI application fails to allow access. </p>
 897
 898 <p>By default, control is not passed on and a failed access check will result in a
 899 Forbidden reply. Disabling the default should be carefully considered.</p>
 900
 901 <hr>
 902
 903 <h3 ALIGN="center"><a href="http://www.FastCGI.com/">www.FastCGI.com</a></h3>
 904 </body>
 905 </html>