FastCGI plug-in provides the following Server Application Functions (SAFs):
The various parameters and "error-reason" strings for the FastCGI SAFs are described in the following sections:
auth-fastcgi is a PatchCheck function. This function is used to forward the request to an “Authorizer” FastCGI application. On successful authorization, a return code of 200 is sent. Otherwise, the response from the “Authorizer” FastCGI application is sent back to the user agent.
More information on the FastCGI Roles can be found here http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6.
The parameters accepted by auth-fastcgi SAF, are available at: FastCGI SAF Parameters.
The following obj.conf code example demonstrates the use of auth-fastcgi:
PathCheck fn="auth-fastcgi" app-path="/usr/bin/perl" app-args="/fastcgi/apps/auth/SimpleAuth.pl" bind-path="localhost:3432".
The responder-fastcgi is a Service function. This function is used to forward the request to a FastCGI application that acts as a “Responder”. The response from the Responder application is sent back to the user agent. More information on the FastCGI Roles can be found at http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6.
The list of parameters accepted by responder-fastcgi SAF are available at:FastCGI SAF Parameters .
The following obj.conf code example demonstrates the use of responder-fastcgi:
Service fn="responder-fastcgi" app-path="/fastcgi-enabled-php-installation/bin/php" bind-path="localhost:3433" app-env="PHP_FCGI_CHILDREN=8" app-env="PHP_FCGI_MAX_REQUEST=500".
The filter-fastcgi is a Service function. This function is used to forward the request to a “Filter” type of FastCGI application. The “Filter” application receives the information associated with the HTTP request and also the data from the file stored on the server. The “Filter” application then generates a “filtered” version of the data stream as the response. This response is sent back to the user agent. More information on the FastCGI Roles can be found at http://www.fastcgi.com/devkit/doc/fcgi-spec.html#S6.
The list of parameters accepted by filter-fastcgi SAF are available at:FastCGI SAF Parameters .
The following obj.conf code example demonstrates the use of filter-fastcgi:
Service fn="filter-fastcgi" app-path="/fastcgi/apps/filter/SimpleFilter" bind-path="localhost:3434" app-env="LD_LIBRARY_PATH=/fastcgi/fcgi-2.4/libfcgi/.libs" min-procs=2
The error-fastcgi is an Error function. The error-fastcgi SAF handles the errors specific to the FastCGI plug-in. This function however does not handle the HTTP errors. On error, FastCGI plug-in can be configured to display a specific page or redirect the request to a specific URL.
The list of parameters accepted by error-fastcgi SAF, are available at: FastCGI SAF Parameters.
The following obj.conf snippet demonstrates the use of error-fastcgi:
Error fn="error-fastcgi" error-reason="Invalid Parameters" error-url="http://www.foo.com/errorPage.html"
See FastCGI SAF Parameters for information on the error-fastcgi parameters.
The FastCGI plug-in SAFs, "auth-fastcgi“ , “responder-fastcgi” and “filter-fastcgi”, all accept the following parameters unless otherwise mentioned explicitly:
bind-path - (Optional) Can be a UNIX Domain Socket name or Named Pipes or of the form host:port. The description of app-path parameter explains the usage of bind-path parameter.
app-path - (Optional) FastCGI application path that processes the request. The functionality is dependent on the value of the bind-path parameter as follows:
If only app-path is specified, the plug-in creates FastCGI applications that listen to UNIX Domain Sockets or Named Pipes created by the plug-in.
If both app-path and bind-path are specified, the plug-in starts the specified FastCGI application process and binds them to the specified bind-path.
If only bind-path is specified, the FastCGI application is considered to be running remotely and the plug-in will not start the FastCGI application process.
If “app-path“ and “bind-path“ both are not specified, then the plug-in logs an error message.
app-args — (Optional) Values that are passed as arguments to the FastCGI application process. Multiple app-args parameters are allowed. The format for the multiple app-args parameters is app-args="value" app-args="value" ...
app-env - (Optional) Value pairs that are passed as environment variables to the FastCGI application process. Multiple “app-env“ parameters are allowed. The format for multiple app-env parameters is app-env="name=value" app-env="name=value". The existing Web Server environment variables are not passed on to the FastCGI programs. Hence, you should explicitly set the environment variables for FastCGI programs using app-env.
To compile a PHP program, you should ensure that the library files are configured correctly.
For example, if you want to load PHP binaries that you have compiled as a FastCGI application, you need to ensure that all the dependent library files, /usr/local/lib and /usr/local/mysql/lib, are exported to LD_LIBRARY_PATH.
On Windows, app-env="Path=c:/php/lib:c:/mysql/lib"
app-env also enables you to export other environment variables to the PHP applications. You can specify the php.ini file location as the followingapp-env="PHPRC=<directory path>".
While using PHP, you need to provide higher value to PHP_FCGI_CHILDREN and PHP_FCGI_MAX_REQUESTS so that it takes the higher precedence while configuring PHP with FastCGI.
min-procs - (Optional) Integer specifying the minimum number of FastCGI application processes to be created. Defaults to 1.
max-procs - (Optional) Integer specifying the maximum number of FastCGI application processes that can be created at any time. The integer value must be equal to or greater than min-procs. Defaults to 1.
The default value is at present a non-operational parameter. For more information about this issue, seeFastCGI in Sun Java System Web Server 7.0 Update 4 Release Notes.
reuse-connection - (Optional) Boolean value that determines if connections to FastCGI applications are reused. False (0, false, no) indicates that the connections to FastCGI applications are closed after each request. True (1, true, yes) indicates that existing connections are reused for new requests. The default is false. See also connection-timeout.
connection-timeout - (Optional) If “reuse-connection " is set to True, then this value specifies the timeout value in seconds for the pooled connections. If a connection is idle for the specified amount period of time, then the plug-in closes the connection. The default value for this parameter is 5 seconds. See also reuse-connection .
resp-timeout - (Optional) Integer that represents the FastCGI server response timeout in seconds. If there is no response from the FastCGI application within the specified period of time, the request is discarded. The default value for this parameter is 5 minutes.
restart-interval - (Optional) Integer that represents the time interval (in minutes) after which the FastCGI application is restarted. The default value for this parameter is 60 minutes (1 hour). If the value for this parameter is set to zero, the FastCGI application is not forced to restart.
req-retry - (Optional) Integer that represents the number of times the plug-in should resend the request when the FastCGI application rejects the request. The default value for this parameter is zero.
listen-queue - (Optional) Integer specifying the listen queue size for the socket. The default value for this parameter is 256.
rlimit_cpu — Specifies the maximum amount of CPU time (in seconds) to be used by a FastCGI program. You can specify only the current (soft) limit. A maximum (hard) limit is not applicable for this parameter and will be ignored.
Note that parameters chroot, user, group, nice, chdir, rlimit_as, rlimit_core and rlimit_nofile are applicable to UNIX platforms only. On Windows platforms, these parameters are ignored.
chroot - (Optional UNIX only) Used to set the root directory of the chroot FastCGI server application processes.
user - (Optional UNIX only) Specifies the user ID the FastCGI application runs as. Defaults to Web Server's user ID.
group - (Optional UNIX only) The FastCGI application will be running under the specified group. Defaults to Web Server's group.
nice - (Optional UNIX only) Specifies the nice/ priority value of FastCGI application processes.
chdir - (Optional UNIX only) Specifies the directory to chdir to after chroot, but before execution begins.
rlimit_as - (Optional UNIX only) Specifies the maximum CGI program address space (in bytes). You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value.
rlimit_core - (Optional UNIX only) Specifies the maximum CGI program core file size. A value of 0 disables writing cores. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value.
rlimit_nofile - (Optional UNIX only) Specifies the maximum number of file descriptors for the CGI program. You can supply both current (soft) and maximum (hard) limits, separated by a comma. The soft limit must be listed first. If only one limit is specified, both the limits are set to this value.
The error-fastcgi Server Application Function (SAF) accepts the following parameters:
error-url - Specifies the page, URI or URL to be displayed in case of if a failure or error occurs. The value of this parameter can be an absolute path, a path relative to docroot, or an URL or URI.
error-reason - (Optional) String that represents the FastCGI protocol error. This string is used to differentiate error URLs to be displayed, in case of any plug-in errors.
This section provides a list of all the valid "error-reason" strings and their descriptions:
“Missing or Invalid Config Parameters” : whenever app-path and bind-path are not specified.
“Stub Start Error” : failure to start the Fastcgisub process.
“Stub Connection Failure” : unable to connect to Fastcgistub.
“No Permission” : FastCGI application or the Fastcgisub has no execute permission.
“Stub Request Handling Error” : unable to send the request to stub, received invalid or no response from the stub for a request, and so on.
“Set Parameter Failure” : when set user, group, chroot, niceor other parameters fail.
“Invalid user and/or group” : when user or group is invalid.
“Server Process Creation Failure” : FastCGI application execution failure or the FastCGI application is unable to bind to the specified address.
“Fastcgi Protocol Error” : FastCGI application contains header with invalid FastCGI version or the role.
“Internal Error” : unable to open the file to be sent to the filter application or any other unknown errors..