docs/mod_fastcgi.html

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