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 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:
Note that parameters chroot, user, group and nice are applicable to only UNIX platforms. On Windows platforms, these parameters are ignored.
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 listens to UNIX Domain Sockets created by the plug-in. This parameter however is accepted only on UNIX platform. On Windows, an error message is logged.
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. So, 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 the 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" ...
bind-path - (Optional) Can be a Unix Domain Socket name or of the form “host:port“. The description of " app-path“ parameter explains the usage of “bind-path“ parameter. Note that the Unix Domain Socket name is applicable only on UNIX platforms. On Windows platforms, bind-path must be specified as “host:port ".
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.
chroot - (Optional) Used to set the root directory of the chroot FastCGI server application processes. Defaults to the Web Server's root directory.
user - (Optional) Specifies the user ID the FastCGI application runs as. Defaults to Web Server's user ID.
group - (Optional) The FastCGI application will be running under the specified group. Defaults to Web Server's group.
nice - (Optional) Specifies the nice/ priority value of FastCGI application processes.
listen-queue - (Optional) Integer specifying the listen queue size for the socket. The default value for this parameter is 256.
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"....
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. 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.
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, nice and so on 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..