FastCGI Directives: IBM HTTP Server
System Administration IBM HTTP Server documentation

FastCGI Directives


FastCgiAccessChecker

  • Default - Directory
  • Syntax - FastCgiAccessChecker filename [-compat]

The FastCgiAccessChecker directive is used to define a FastCGI application as a per-directory access validator. The Apache Access phase precedes user authentication and the decision to allow access to the requested resource is based on the HTTP headers submitted with the request. FastCGI based authorizers are useful when there is a dynamic component to the access validation decision, such as a time of day, or whether or not a domain account is current.

If the FastCGI application filename does not have a corresponding static or external server definition, the application is started as a dynamic FastCGI application. If the filename does not begin with a slash (/), then the filename is assumed relative to the ServerRoot.

FastCgiAccessChecker is used within Directory or Location containers.

<Directory htdocs/protected>
FastCgiAccessChecker fcgi-bin/access-checker
</Directory>

Mod_fastcgi sends nearly all of the standard environment variables typically available to CGI/FastCGI request handlers. All headers returned by a FastCGI access-checker application in a successful response (Status: 200) are passed to subprocesses (CGI/FastCGI invocations) as environment variables. All headers returned in an unsuccessful response are passed to the client. FastCGI specification compliant behavior is obtained, by using the "-compat" option.

Mod_fastcgi sets the environment variable "FCGI_APACHE_ROLE" to "ACCESS_CHECKER", to indicate which (Apache-specific) authorizer phase is performed.

Custom failure responses from FastCGI authorizer applications are not supported. See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).

FastCgiAccessCheckerAuthoritative

  • Context - Directory
  • Default - FastCgiAccessCheckerAuthoritative On
  • Syntax - FastCgiAccessCheckerAuthoritative On | Off

Setting the FastCgiAccessCheckerAuthoritative directive explicitly to Off, allows access checking passing to lower level modules (as defined in the Configuration and modules.c files), if the FastCGI application fails to allow access.

By default, control is not passed on and a failed access check results in a forbidden reply. Careful consideration is recommended before disabling the default.

FastCgiAuthenticator

  • Context - Directory
  • Syntax - FastCgiAuthenticator filename [-compat]

The FastCgiAuthenticator directive is used to define a FastCGI application as a per-directory authenticator. Authenticators verify the requester, by matching the provided username and password against a list or database of known users and passwords. FastCGI based authenticators are useful when the user database is maintained within an existing independent program, or resides on a machine other than the Web server.

If the FastCGI application filename does not have a corresponding static or external server definition, the application is started as a dynamic FastCGI application. If the filename does not begin with a slash (/), then the filename is assumed relative to the ServerRoot.

FastCgiAuthenticator is used within Directory or Location containers and must include an AuthType and AuthName directive. Only the Basic user authentication type is supported. This type needs a require or FastCgiAuthorizer directive, to work correctly.

<Directory htdocs/protected>
AuthType Basic
AuthName ProtectedRealm
FastCgiAuthenticator fcgi-bin/authenticator
require valid-user
</Directory>

Mod_fastcgi sends nearly all of the standard environment variables typically available to CGI/FastCGI request handlers. All headers returned by a FastCGI authentication application in a successful response (Status: 200) are passed to subprocesses (CGI/FastCGI invocations) as environment variables. All headers returned in an unsuccessful response are passed to the client. FastCGI specification compliant behavior is obtained, by using the "-compat" option.

Mod_fastcgi sets the environment variable "FCGI_APACHE_ROLE" to "AUTHENTICATOR" to indicate which (Apache-specific) authorizer phase is performed.

Custom failure responses from FastCGI authorizer applications are not supported. See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).

FastCgiAuthenticatorAuthoritative

  • Context - Directory
  • Default - FastCgiAuthenticatorAuthoritative On
  • Syntax - FastCgiAuthenticatorAuthoritative On | Off

Setting the FastCgiAuthenticatorAuthoritative directive explicitly to Off allows authentication passing to lower level modules (as defined in the Configuration and modules.c files) if the FastCGI application fails to authenticate the user.

A common use for this directive is in conjunction with a well protected AuthUserFile containing a few (administration related) users. 

By default, control is not passed on and an unknown user results in an Authorization Required reply.  Careful consideration is recommended before disabling the default.

FastCgiAuthorizer

  • Context - Directory
  • Syntax - FastCgiAuthorizer filename [-compat]

The FastCgiAuthorizer directive is used to define a FastCGI application as a per-directory authorizer.  Authorizers validate whether an authenticated user is allowed access to a requested resource.  FastCGI-based authorizers are useful when there is a dynamic component to the authorization decision, such as a time of day, or whether or not the user has paid his bills. 

If the FastCGI application filename does not have a corresponding static or external server definition, the application is started as a dynamic FastCGI application.  If the filename does not begin with a slash (/) then the filename is assumed relative to the ServerRoot.

FastCgiAuthorizer is used within Directory or Location containers and must include an AuthType and AuthName directive. This directive requires an authentication directive, such as FastCgiAuthenticator, AuthUserFile, AuthDBUserFile, or AuthDBMUserFile to work correctly.

.

<Directory htdocs/protected>
AuthType Basic
AuthName ProtectedRealm
AuthDBMUserFile conf/authentication-database
FastCgiAuthorizer fcgi-bin/authorizer
</Directory>

Mod_fastcgi sends nearly all of the standard environment variables typically available to CGI/FastCGI request handlers.  All headers returned by a FastCGI authentication application in a successful response (Status: 200) are passed to subprocesses (CGI/FastCGI invocations) as environment variables.  All headers returned in an unsuccessful response are passed on to the client.  FastCGI specification compliant behavior is obtained by using the "-compat" option.

Mod_fastcgi sets the environment variable "FCGI_APACHE_ROLE" to "AUTHORIZER", to indicate which (Apache-specific) authorizer phase is being performed.

Custom failure responses from FastCGI authorizer applications are not supported.  See the ErrorDocument directive for a workaround (a FastCGI application can serve the document).

FastCgiAuthorizerAuthoritative

  • Context - Directory
  • Default - FastCgiAuthorizerAuthoritative On
  • Syntax - FastCgiAuthorizerAuthoritative On | Off

Setting the FastCgiAuthenticatorAuthoritative directive explicitly to Off allows authentication passing to lower level modules (as defined in the Configuration and modules.c files), if the FastCGI application fails to authenticate the user.

A common use for this directory is in conjunction with a well protected AuthUserFile containing a few (administration related) users. 

By default, control is not passed on and an unknown user results in an Authorization Required reply.  Careful consideration is recommended before disabling the default.

FastCgiConfig

  • Context - Server config
  • Syntax - FastCgiConfig option option ...

The FastCgiConfig directive defines the default parameters for all dynamic FastCGI applications. This directive does not affect static or external applications.

Dynamic applications are started upon demand. If the demand is heavy, additional application instances are started. As the demand fades, application instances are killed off. Many of the options govern this process.

Option can include one of the following (case insensitive):

appConnTimeout n (0 seconds)
The number of seconds to wait for a connection to the FastCGI application to complete or 0, to indicate use of a blocking connect().  If the timeout expires, a  SERVER_ERROR results.  For non-zero values, this is the amount of time used in a select() to write to the file descriptor returned by a non-blocking connect().  Non-blocking connect()s are troublesome on many platforms.  See also -idle-timeout; this option produces similar results, but in a more portable manner.
idle-timeout n (30 seconds)
The number of seconds of FastCGI application inactivity allowed before the request is aborted and the event is logged (at the error LogLevel).  The inactivity timer applies only as long as a connection is pending with the FastCGI application.  If a request is queued to an application, but the application does not respond (by writing and flushing) within this period, the request is aborted.  If communication is complete with the application, but incomplete with the client (the response is buffered), the timeout does not apply.
autoUpdate none
This option causes mod_fastcgi to check the age of the application on disk before processing each request.  If the application is more recent, the process manager is notified and all running instances of the application are killed off.  Building this type of functionality into the application is preferable (e.g. every 100th request it checks to see if there is a newer version on disk and exits if so).   An outstanding problem (bug) may exist when this option is used with -restart.
gainValue n (0.5)
A floating point value between 0 and 1 that is used as an exponent in the computation of the exponentially decayed connection times load factor of the currently running dynamic FastCGI applications.  Old values are scaled by (1 - gainValue), so making values smaller, weights them more heavily compared to the current value, which is scaled by gainValue.
initial-env name[=value] none
A name-value pair passed in the initial environment when instances of the application are spawned.  To pass a variable from the Apache environment, do not provide the "=" (if the variable is not actually in the environment, it is defined without a value).  To define a variable without a value, provide the "=" without any value.  This option is repeatable.
init-start-delay n (1 second)
The minimum number of seconds between the spawning of instances of this application.   This delay decreases the demand placed on the system at server initialization.
killInterval n (300 seconds)
The killInterval determines how often the dynamic application instance killing policy is implemented within the process manager.  Lower numbers result in a more aggressive policy, while higher numbers result in a less aggressive policy.
listen-queue-depth n (100)
The depth of listen() queue (also known as the backlog) shared by all instances of this application.  A deeper listen queue allows the server to cope with transient load fluctuations without rejecting requests; it does not increase throughput.   Adding additional application instances may increase throughput and performance, depending upon the application and the host.
maxClassProcesses n (10)
The maximum number of dynamic FastCGI application instances allowed to run for any one FastCGI application.
maxProcesses n (50)
The maximum number of dynamic FastCGI application instances allowed to run at any time.
minProcesses n (5)
The minimum number of dynamic FastCGI application instances allowed to run at any time, without being killed off by the process manager (due to lack of demand).
multiThreshhold n (50)
An integer between 0 and 100 used to determine whether to terminate any instance of a FastCGI application.  If the application has more than one instance currently running, this attribute is used to decide whether to terminate one of them.  If only one instance remains, singleThreshhold is used instead.
pass-header header none
The name of an HTTP Request Header passed in the request environment.  This option makes the contents of headers available (e.g. Authorization) to a CGI environment.
priority n (0)
The process priority to assign to the application instances (using setpriority()).
processSlack n (5 seconds)
If the sum of all currently running dynamic FastCGI applications exceeds maxProcesses - processSlack, the process manager invokes the killing policy.  This action improves performance at higher loads, by killing some of  the most inactive application instances before reaching maxProcesses.
restart none
This option causes the process manager to restart dynamic applications upon failure (similar to static applications).
restart-delay n (5 seconds)
The minimum number of seconds between the respawning of failed instances of this application.  This delay prevents a broken application from soaking up too much of the system.
singleThreshhold n (0)
An integer between 0 and 100, used to determine whether the last instance of a FastCGI application can terminate.  If the process manager computed load factor for the application is lower than the specified threshold, the last instance is terminated.   Specify a value closer to 1, to make your executables run in the "idle" mode for a long time. If memory or CPU time is a concern, a value closer to 100 is more applicable.  A value of 0, will prevent the last instance of an application from being terminated; this value is the default. Changing this default is not recommended (especially if -appConnTimeout is set).
startDelay n (3 seconds)
The number of seconds the Web server waits while trying to connect to a dynamic FastCGI application.  If the interval expires, the process manager is notified with hope that another instance of the application will start.  The startDelay must be smaller than appConnTimeout, to be effective.
updateInterval n  (300 seconds)
The updateInterval determines how often statistical analysis is performed to determine the fate of dynamic FastCGI applications.

FastCgiExternalServer

  • Context - Server config
  • Syntax - FastCgiExternalServer filename -host hostnameport [-appConnTimeout n]
    FastCgiExternalServer filename -socket filename [-appConnTimeout n]
appConnTimeout n (0 seconds)
The number of seconds to wait for a connection to the FastCGI application to complete, or 0, to indicate use of a blocking connect().  If the timeout expires, a  SERVER_ERROR results.  For non-zero values, this is the amount of time used in a select() to write to the file descriptor returned by a non-blocking connect().  Non-blocking connect()s are troublesome on many platforms.  See also -idle-timeout; this option produces similar results, but in a more portable manner.
idle-timeout n (30 seconds)
The number of seconds of FastCGI application inactivity allowed before the request is aborted and the event is logged (at the error LogLevel).  The inactivity timer applies only as long as a connection is pending with the FastCGI application.  If a request is queued to an application, but the application does not respond (by writing and flushing) within this period, the request is aborted.  If communication is complete with the application but incomplete with the client (the response is buffered), the timeout does not apply.
flush none
Force a write to the client as data is received from the application.  By default, mod_fastcgi buffers data to free the application quickly.
host hostname:port none
The hostname, or IP address and TCP port number (1-65535) the application uses for communication with the Web server. The -socket and -host options are mutually exclusive.
Pass-header header none
The name of an HTTP Request Header passed in the request environment.  This option makes available the contents of headers, which are normally not available (e.g. Authorization) to a CGI environment.
socket filename none
UNIX: The filename of the UNIX domain socket the application uses for communication with the Web server.  The filename is relative to the FastCgiIpcDir.  The -socket and -port options are mutually exclusive.
Windows NT:  The name of the pipe the application uses for communicating with the Web server. The name is relative to the FastCgiIpcDir.  The -socket and -port options are mutually exclusive.

FastCgiIpcDir

  • Context - Server config
  • Default - UNIX - FastCgiIpcDir /tmp/fcgi, Windows NT - FastCgiIpcDir \\.\pipe\ModFastCgi\
  • Syntax - UNIX - FastCgiIpcDir directory, Windows NT - FastCgiIpcDir name
Applies to UNIX platforms

UNIX: The FastCgiIpcDir directive specifies directory as the place to store (and find, in the case of external FastCGI applications) the UNIX socket files used for communication between the applications and the Web server. If the directory does not begin with a slash (/) then it is assumed relative to the ServerRoot. If the directory does not exist, an attempt is made to create the directive with appropriate permissions. Do not specify a directory that is not on a local file system. If you use the default directory (or another directory within /tmp), mod_fastcgi breaks, if your system periodically deletes files from /tmp.

Applies to windows NT

Windows NT: The FastCgiIpcDir directive specifies name as the root for the named pipes used for communication between the application and the Web server. Put the name in the form \\.\pipe\pipename. The pipename part can contain any character, other than a backslash.

The FastCgiIpcDir directive must precede any FastCgiServer or FastCgiExternalServer directives (which make use of UNIX sockets). Ensure the directory is readable, writeable, and executable (searchable) by the Web server; no one should have access to this directory.

FastCgiServer

  • Context - Server config
  • Syntax -FastCgiServer filename option option ...

The FastCgiServer directive defines filename as a static FastCGI application. If the filename does not begin with a slash (/), then this filename is assumed relative to the ServerRoot.

By default, the Process Manager starts one instance of the application with the default configuration specified (in parenthesis) below. Should a static application instance die for any reason, mod_fastcgi spawns another instance for replacement and logs the event (at the warn LogLevel).

Option can be one of (case insensitive):

appConnTimeout n (0 seconds)
The number of seconds to wait for a connection to the FastCGI application to complete, or 0, to indicate use of a blocking connect().   If the timeout expires, a  SERVER_ERROR results.  For non-zero values, this is the amount of time used in a select() to write to the file descriptor returned by a non-blocking connect().  Non-blocking connect()s are troublesome on many platforms.  See also -idle-timeout, it produces similar results but in a more portable manner.
idle-timeout n (30 seconds)
The number of seconds of FastCGI application inactivity allowed before the request is aborted and the event is logged (at the error LogLevel).  The inactivity timer applies only as long as a connection is pending with the FastCGI application.  If a request is queued to an application, but the application does not respond (by writing and flushing) within this period, the request is aborted.  If communication is complete with the application, but incomplete with the client (the response is buffered), the timeout does not apply.
initial-env name[=value] none] none
A name-value pair passed in the FastCGI application  initial environment.  To pass a variable from Apache's environment, do not provide the "=" (a variable that is not actually in the environment, is defined without a value).  To define a variable without a value, provide the "=" without a value.  This option is repeatable.
init-start-delay n(1 second)
The minimum number of seconds between the spawning of instances of this application.   This delay decreases the demand placed on the system at server initialization.
Flush none
Force a write to the client as data is received from the application.  By default, mod_fastcgi buffers data to free the application quickly.
Listen-queue-depth n (100)
The depth of listen() queue (also known as the backlog) shared by all of the instances of this application.  A deeper listen queue allows the server to cope with transient load fluctuations, without rejecting requests; this option does not increase throughput.   Adding additional application instances can increase throughput and performance, depending upon the application and the host.
Pass-header header none
The name of an HTTP Request Header passed in the request environment.  This option makes the contents of headers available (e.g. Authorization) to a CGI environment.
processes n (1)
The number of application instances to spawn at server initialization.
Priority n (0)
The process priority assigned to the application instances (using setpriority()).
port n none
The TCP port number (1-65535) the application uses for communication with the Web server.  This option makes the application accessible from other machines on the network as well.  The -socket and -port options are mutually exclusive.
Restart-delay n (5 seconds)
The minimum number of seconds between the respawning of failed instances of this application.  This delay prevents a broken application from soaking up too much of the system.
Socket filename (gen'd)
Applies to UNIX platforms
UNIX: The filename of the UNIX domain socket that the application uses for communication with the Web server.  The module creates the socket within the directory specified by FastCgiIpcDir.  This option makes the application accessible to other applications (e.g. cgi-fcgi) on the same machine, or via an external FastCGI application definition (FastCgiExternalServer).  If neither the -socket nor the -port options are given, the module generates a UNIX domain socket filename.  The -socket and -port options are mutually exclusive.
Applies to Windows NT Windows NT: The name of the pipe that the application should use for communication with the Web server.  The module creates the named pipe off the named pipe root specified by the FastCgiIpcDir. This option makes the application accessible to other applications,like cgi-fcgi on the same machine or via an external FastCGI application definition,FastCgiExternalServer). If neither the -socket nor the -port options are given, the module generates a name for the named pipe. The -socket and -port options are mutually exclusive.
 

FastCgiSuexec

  • Context - Server config
  • Default - FastCgiSuexec Off
  • Syntax - FastCgiSuexec On | Off | filename

The FastCgiSuexec directive is used to enable support for a suexec-wrapper.  FastCgiSuexec requires that suexec enabling in Apache (for CGI).  To use the same suexec-wrapper used by Apache, set FastCgiSuexec to On.  To use a different suexec-wrapper, specify the filename of the suexec-wrapper.  If the filename does not begin with a slash (/), then the filename is assumed relative to the ServerRoot.

When FastCgiSuexec is enabled, the location of static or external FastCGI application definitions is important.  These differences inherit their user and group from the User and Group directives in the virtual server in which they were defined.  User and Group directives should precede FastCGI application definitions.   This function does not limit the FastCGI application to the virtual server in which it was defined, the application is allowed to service requests, from any virtual server with the same user and group.  If a request is received for a FastCGI application, without an existing matching definition running with the correct user and group, a dynamic instance of the application is started with the correct user and group.   This action can lead to multiple copies of the same application running with different user/group.  If this is a problem, preclude navigation to the application from other virtual servers, or configure the virtual servers with the same User and Group.

See the Apache documentation for more information about suexec (make sure you fully understand the security implications).

 
Related information...

     (Back to Top)