docs/mod_fastcgi.html

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