FastCGI directives

Home

These configuration parameters control the FastCGI feature in IBM HTTP Server.

FastCGIAccessChecker directive
FastCGIAccessCheckerAuthoritatve directive
FastCGIAuthenticator directive
FastCGIAuthenticatorAuthoritative directive
FastCGIAuthorizer directive
FastCGIAuthorizerAuthoritative directive
FastCGIConfig directive
FastCGIExternalServer directive
FastCGIIpcDir directive
FastCGIServer directive
FastCGIsuEXEC directive

FastCGIAccessChecker directive

The FastCGIAccessChecker directive defines a FastCGI application as a per-directory access validator.

Syntax FastCGIAccessChecker file name [-compat]
Scope directory, location
Default Directory
Module mod_fastcgi
Multiple instances in the configuration file yes
Values File name

The Apache Access phase precedes user authentication and the HTTP headers submitted with the request determine the decision to enable access to the requested resource. Use FastCGI-based authorizers when a dynamic component exists as part of the access validation decision, like the time, or the status of a domain account.
If the FastCGI application file name does not have a corresponding static or external server definition, the application starts as a dynamic FastCGI application. If the file name does not begin with a slash (/), then the application assumes that the file name is relative to the ServerRoot. Use the FastCgiAccessChecker directive within Directory or Location containers. For example:
<Directory htdocs/protected>
FastCgiAccessChecker fcgi-bin/access-checker
</Directory>
Mod_fastcgi sends nearly all of the standard environment variables typically available to CGI and FastCGI request handlers. All headers returned by a FastCGI access-checker application in a successful response (Status: 200), pass to subprocesses, or CGI and FastCGI invocations, as environment variables. All headers returned in an unsuccessful response pass to the client. Obtain FastCGI specification compliant behavior by using the -compat option.
Mod_fastcgi sets the environment variable FCGI_APACHE_ROLE to ACCESS_CHECKER, to indicate the Apache-specific authorizer phase performed.
The HTTP Server does not support custom failure responses from FastCGI authorizer applications. See the ErrorDocument directive for a workaround. A FastCGI application can serve the document.
FastCGIAccessCheckerAuthoritatve directive

The FastCGIAccessCheckerAuthoritatve directive enables access checking passing to lower level modules.

Syntax FastCGIAccessCheckerAuthoritative On | Off
Scope directory, location
Default FastCGIAccessCheckerAuthoritative On
Module mod_fastcgi
Multiple instances in the configuration file yes
Values On or off

Setting the FastCgiAccessCheckerAuthoritative directive explicitly to Off, enables access checking passing to lower level modules, as defined in the Configuration and modules.c files, if the FastCGI application fails to enable access.
By default, control does not pass on and a failed access check results in a forbidden reply. Consider the implications carefully before disabling the default.
FastCGIAuthenticator directive

The FastCGIAuthenticator directive defines a FastCGI application as a per-directory authenticator.

Syntax FastCGIAuthenticator file name [-compat]
Scope directory
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values File name

Authenticators verify the requester by matching the user name and password that is provided against a list or database of known users and passwords. Use FastCGI-based authenticators 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 file name does not have a corresponding static or external server definition, the application starts as a dynamic FastCGI application. If the file name does not begin with a slash (/), then the file name is assumed to be relative to the ServerRoot.
Use the FastCgiAuthenticator directive within or location containers, along with an AuthType and AuthName directive. This directive only supports the basic user authentication type. This authentication 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>
The Mod_fastcgi directive sends nearly all of the standard environment variables that are typically available to CGI and FastCGI request handlers. All headers returned by a FastCGI authentication application in a successful response (Status: 200) pass to subprocesses, or CGI and FastCGI invocations, as environment variables. All headers returned in an unsuccessful response are passed to the client. Obtain FastCGI specification compliant behavior by using the -compat option.
The Mod_fastcgi directive sets the FCGI_APACHE_ROLE environment variable to AUTHENTICATOR, indicating the Apache-specific authorizer phase performed.
This directive does not support custom failure responses from FastCGI authorizer applications. See the ErrorDocument directive for a workaround. A FastCGI application can serve the document.
FastCGIAuthenticatorAuthoritative directive

The FastCGIAuthenticatorAuthoritative directive enables authentication passing to lower level modules defined in the configuration and modules.c files, if explicitly set to off and the FastCGI application fails to authenticate the user.

Syntax FastCGIAuthenticatorAuthoritative On | Off
Scope directory
Default FastCgiAuthenticatorAuthoritative On
Module mod_fastcgi
Multiple instances in the configuration file yes
Values On or off

Use this directive in conjunction with a well protected AuthUserFile directive, containing a few administration-related users.
By default, control does not pass on and an unknown user results in an Authorization Required reply. Consider implications carefully before disabling the default.
FastCGIAuthorizer directive

The FastCGIAuthorizer directives defines a FastCGI application as a per-directory authorizer.

Syntax FastCgiAuthorizer file name [-compat]
Scope directory
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values File name

Authorizers validate whether an authenticated user can access a requested resource. Use FastCGI-based authorizers when a dynamic component exists as part of the authorization decision, such as the time, or currency of the user's bills.
If the FastCGI application file name does not have a corresponding static or external server definition, the application starts as a dynamic FastCGI application. If the file name does not begin with a slash (/) then the file name is assumed relative to the ServerRoot.
Use FastCgiAuthorizer within Directory or Location containers. 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>
The Mod_fastcgi directive sends nearly all of the standard environment variables typically available to CGI and FastCGI request handlers. All headers returned by a FastCGI authentication application in a successful response (Status: 200) pass to subprocesses, or CGI and FastCGI invocations, as environment variables. All headers returned in an unsuccessful response pass on to the client. Obtain FastCGI specification compliant behavior by using the -compat option.
The Mod_fastcgi directive sets the environment variable FCGI_APACHE_ROLE to AUTHORIZER, to indicate the Apache-specific authorizer phase performed.
This directive does not support custom failure responses from FastCGI authorizer applications. See the ErrorDocument directive for a workaround. A FastCGI application can serve the document.
FastCGIAuthorizerAuthoritative directive

The FastCGIAuthorizerAuthoritative directive enables authentication passing to lower level modules, as defined in the configuration and modules.c files, when explicitly set to Off, if the FastCGI application fails to authenticate the user.

Syntax FastCgiAuthorizerAuthoritative file name On | Off
Scope directory
Default FastCgiAuthorizerAuthoritative file name On
Module mod_fastcgi
Multiple instances in the configuration file yes
Values On or off

Use this directive in conjunction with a well protected AuthUserFile containing a few administration-related users.
By default, control does not pass on and an unknown user results in an Authorization Required reply. Consider the implications carefully before disabling the default.
FastCGIConfig directive

The FastCGIConfig directive defines the default parameters for all dynamic FastCGI applications.

Syntax FastCgiConfig option option...
The FastCgiConfig directive does not affect static or external applications.
Scope directory
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values Dynamic applications start upon demand. Additional application instances start to accommodate heavy demand. As demand fades, the number of application instances decline. 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 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 aborts and the event logs at the error LogLevel. The inactivity timer applies only when a pending connection with the FastCGI application exists. If an application does not respond to a queued request within this period, the request aborts. If communicationcompletes with the application, but not with the client (a buffered response), the timeout does not apply.
autoUpdate none. This option causes the mod_fastcgi module to check the age of the application on disk before processing each request. For recent applications, this function notifies the process manager and stops all running instances of the application. Build this type of functionality into the application. A problem can occur when using this option 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 spawn. 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 the 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 can 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 the process manager allows to run at any time, without killing them 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 helps 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 to a CGI environment.
priority n (0). The process priority assigned 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 the maxProcesses value.
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, prevents the last instance of an application from terminating; this value is the default. Changing this default is not recommended, especially if we set the -appConnTimeout option.
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 starts. Set the startDelay value smaller than the appConnTimeout value, to be effective.
updateInterval n (300 seconds). The updateInterval decides how often statistical analysis is performed to determine the fate of dynamic FastCGI applications.

FastCGIExternalServer directive

The FastCGIExternalServer defines file name as an external FastCGI application.
It operates the same as the Fastcgiserver directive, except that the CGI application is running in another process outside of the Web server.

Syntax FastCgiExternalServer file name -host hostnameport [-appConnTimeout n] FastCgiExternalServer file name -socket file name [-appConnTimeout n]
Scope Server configuration
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values

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() method. If the timeout expires, a SERVER_ERROR results. For non-zero values, this indicator is the amount of time used in a select() method to write to the file descriptor returned by a non-blocking connect() method.
Non-blocking connect() methods 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 aborts 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 aborts. If communication iscomplete with the application but incomplete with the client (a buffered response), the timeout does not apply.
flush none. Force a write to the client as data is received from the application. By default, the mod_fastcgi option 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 the header contents available, to a CGI environment.
socket file name none.

On UNIX operating systems. The file name of the UNIX domain socket the application uses for communication with the Web server. The file name is relative to the FastCgiIpcDir option. The -socket and -port options are mutually exclusive.
On Windows operating systems. The name of the pipe the application uses for communicating with the Web server. The name is relative to the FastCgiIpcDir option. The -socket and -port options are mutually exclusive.

FastCGIIpcDir directive

The FastCGIIpcDir directive specifies as the place to store the UNIX socket files used for communication between the applications and the Web server.

Syntax

On UNIX platforms - FastCgiIpcDir directory
On Windows operating systems - FastCgiIpcDir name

Scope Server configuration
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values directory or name

AIX: HP-UX: Linux: Solaris: The FastCgiIpcDir directive specifies as the place to store and find, in the case of external FastCGI applications, the UNIX socket files that are used for communication between the applications and the Web server. If the does not begin with a slash (/) then it is assumed to be relative to the ServerRoot. If the does not exist, the function attempts to create the directive with appropriate permissions. Specify a on a local file system. If we use the default directory, or another within /tmp, mod_fastcgi breaks if wer system periodically deletes files from the /tmp
Windows: The FastCgiIpcDir directive specifies name as the root for the named pipes used for communication between the application and the Web server. Define the name in the form >\\.\pipe\pipename. . The pipename syntax 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 a readable, writeable, and executable directory by the Web server. No one should have access to this
FastCGIServer directive

The FastCGIServer directive defines file name as a static FastCGI application.
The Process Manager starts one instance of the application with the default configuration specified in parentheses below. Should a static application instance die for any reason, the mod_fastcgi module spawns another instance for replacement and logs the event at the warn LogLevel.

Syntax FastCgiServer file name [options]
Scope Server configuration
Default None
Module mod_fastcgi
Multiple instances in the configuration file yes
Values directory or name
You can use one of the following case-insensitive options:

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 indicator 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 prove troublesome on many platforms. See the -idle-timeout option; 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 aborts and the event logs at the error LogLevel. The inactivity timer applies only when a pending connection with the FastCGI application exists. If an application does not respond to a queued request within this period, the request aborts. If communicationcompletes with the application, but does not complete with the client (a buffered response), 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 the Apache environment, do not provide the "=" (variables not actually in the environment, are defined without a value). To define a variable without a value, provide the "=" without a value. You can repeat this option.
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 arrives from the application. By default, mod_fastcgi buffers data to free the application quickly.
Listen-queue-depth n (100). The depth of the listen() queue, also known as the backlog, shared by all of the instances of this application.
A deeper listen queue enables 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 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. 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 using too many system resources.
Socket file name:

On UNIX platforms: The file name of the UNIX domain socket that the application uses for communication with the Web server. The module creates the socket within the specified by FastCgiIpcDir. This option makes the application accessible to other applications, for example, cgi-fcgi on the same machine, or through an external FastCGI application definition, FastCgiExternalServer. If neither the -socket nor the -port options are given, the module generates a UNIX domain socket file name. The -socket and -port options are mutually exclusive.
On Windows operating systems: The name of the pipe for the application to use for communication with the Web server. The module creates the named pipe off the named pipe root specified by the FastCgiIpcDir directive. This option makes the application accessible to other applications, like cgi-fcgi on the same machine or through 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. If the file name does not begin with a slash (/), then this file name is assumed relative to the ServerRoot.

FastCGIsuEXEC directive

The FastCGIsuEXEC directive supports the suEXEC-wrapper.

Syntax FastCgiSuexec On | Off file name
Scope Server configuration
Default FastCgiSuexec Off
Module mod_fastcgi
Multiple instances in the configuration file yes
Values The FastCgiSuexec directive requires 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 file name of the suEXEC-wrapper. If the file name does not begin with a slash (/), then the file name is assumed relative to the ServerRoot.

When you enable the FastCgiSuexec directive, the location of static or external FastCGI application definitions becomes 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 can 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 starts with the correct user and group. This action can lead to multiple copies of the same application running with a different user and group. If this causes 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 and the security implications.

Related tasks

Enable IHS for FastCGI applications

Syntax	FastCGIAccessChecker file name [-compat]
Scope	directory, location
Default	Directory
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	File name

Syntax	FastCGIAccessCheckerAuthoritative On \| Off
Scope	directory, location
Default	FastCGIAccessCheckerAuthoritative On
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	On or off

Syntax	FastCGIAuthenticator file name [-compat]
Scope	directory
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	File name

Syntax	FastCGIAuthenticatorAuthoritative On \| Off
Scope	directory
Default	FastCgiAuthenticatorAuthoritative On
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	On or off

Syntax	FastCgiAuthorizer file name [-compat]
Scope	directory
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	File name

Syntax	FastCgiAuthorizerAuthoritative file name On \| Off
Scope	directory
Default	FastCgiAuthorizerAuthoritative file name On
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	On or off

Syntax	FastCgiConfig option option... The FastCgiConfig directive does not affect static or external applications.
Scope	directory
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	Dynamic applications start upon demand. Additional application instances start to accommodate heavy demand. As demand fades, the number of application instances decline. Many of the options govern this process.

Syntax	FastCgiExternalServer file name -host hostnameport [-appConnTimeout n] FastCgiExternalServer file name -socket file name [-appConnTimeout n]
Scope	Server configuration
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	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() method. If the timeout expires, a SERVER_ERROR results. For non-zero values, this indicator is the amount of time used in a select() method to write to the file descriptor returned by a non-blocking connect() method. Non-blocking connect() methods 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 aborts 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 aborts. If communication iscomplete with the application but incomplete with the client (a buffered response), the timeout does not apply. flush none. Force a write to the client as data is received from the application. By default, the mod_fastcgi option 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 the header contents available, to a CGI environment. socket file name none. On UNIX operating systems. The file name of the UNIX domain socket the application uses for communication with the Web server. The file name is relative to the FastCgiIpcDir option. The -socket and -port options are mutually exclusive. On Windows operating systems. The name of the pipe the application uses for communicating with the Web server. The name is relative to the FastCgiIpcDir option. The -socket and -port options are mutually exclusive.

Syntax	On UNIX platforms - FastCgiIpcDir directory On Windows operating systems - FastCgiIpcDir name
Scope	Server configuration
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	directory or name

Syntax	FastCgiServer file name [options]
Scope	Server configuration
Default	None
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	directory or name

Syntax	FastCgiSuexec On \| Off file name
Scope	Server configuration
Default	FastCgiSuexec Off
Module	mod_fastcgi
Multiple instances in the configuration file	yes
Values	The FastCgiSuexec directive requires 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 file name of the suEXEC-wrapper. If the file name does not begin with a slash (/), then the file name is assumed relative to the ServerRoot.