docs/mod_fastcgi.html

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