docs/mod_fastcgi.html

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