10. FastCGI Applications

HAProxy is able to send HTTP requests to Responder FastCGI applications. This feature was added in HAProxy 2.1. To do so, servers must be configured to use the FastCGI protocol (using the keyword “proto fcgi” on the server line) and a FastCGI application must be configured and used by the backend managing these servers (using the keyword “use-fcgi-app” into the proxy section). Several FastCGI applications may be defined, but only one can be used at a time by a backend.

HAProxy implements all features of the FastCGI specification for Responder application. Especially it is able to multiplex several requests on a simple connection.

10.1. Setup

10.1.1. Fcgi-app section

fcgi-app <name>

fcgi-app <name>

Declare a FastCGI application named <name>. To be valid, at least the document root must be defined.

acl <aclname> <criterion> [flags] [operator] <value> ...

acl <aclname> <criterion> [flags] [operator] <value> ...

Declare or complete an access list.

See “acl” keyword in section 4.2 and section 7 about ACL usage for details. ACLs defined for a FastCGI application are private. They cannot be used by any other application or by any proxy. In the same way, ACLs defined in any other section are not usable by a FastCGI application. However, Pre-defined ACLs are available.

docroot <path>

docroot <path>

Define the document root on the remote host. <path> will be used to build the default value of FastCGI parameters SCRIPT_FILENAME and PATH_TRANSLATED. It is a mandatory setting.

index <script-name>

index <script-name>

Define the script name that will be appended after an URI that ends with a slash ("/") to set the default value of the FastCGI parameter SCRIPT_NAME. It is an optional setting.

Example:

index index.php

log-stderr global

log-stderr global
log-stderr <target> [len <length>] [format <format>]
    [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]]

Enable logging of STDERR messages reported by the FastCGI application.

See “log” keyword in section 4.2 for details. It is an optional setting. By default STDERR messages are ignored.

pass-header <name> [ { if | unless } <condition> ]

pass-header <name> [ { if | unless } <condition> ]

Specify the name of a request header which will be passed to the FastCGI application. It may optionally be followed by an ACL-based condition, in which case it will only be evaluated if the condition is true.

Most request headers are already available to the FastCGI application, prefixed with “HTTP_”. Thus, this directive is only required to pass headers that are purposefully omitted. Currently, the headers “Authorization”, “Proxy-Authorization” and hop-by-hop headers are omitted.

Note that the headers “Content-type” and “Content-length” are never passed to the FastCGI application because they are already converted into parameters.

path-info <regex>

path-info <regex>

Define a regular expression to extract the script-name and the path-info from the URL-decoded path. Thus, <regex> may have two captures: the first one to capture the script name and the second one to capture the path-info. The first one is mandatory, the second one is optional. This way, it is possible to extract the script-name from the path ignoring the path-info. It is an optional setting. If it is not defined, no matching is performed on the path. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not filled.

For security reason, when this regular expression is defined, the newline and the null characters are forbidden from the path, once URL-decoded. The reason to such limitation is because otherwise the matching always fails (due to a limitation one the way regular expression are executed in HAProxy). So if one of these two characters is found in the URL-decoded path, an error is returned to the client. The principle of least astonishment is applied here.

Example:

path-info ^(/.+\.php)(/.*)?$ # both script-name and path-info may be set
path-info ^(/.+\.php)        # the path-info is ignored

option get-values

option get-values
no option get-values

Enable or disable the retrieve of variables about connection management.

HAProxy is able to send the record FCGI_GET_VALUES on connection establishment to retrieve the value for following variables:

* FCGI_MAX_REQS     The maximum number of concurrent requests this
                    application will accept.

* FCGI_MPXS_CONNS   "0" if this application does not multiplex connections,
                    "1" otherwise.

Some FastCGI applications does not support this feature. Some others close the connection immediately after sending their response. So, by default, this option is disabled.

Note that the maximum number of concurrent requests accepted by a FastCGI application is a connection variable. It only limits the number of streams per connection. If the global load must be limited on the application, the server parameters “maxconn” and “pool-max-conn” must be set. In addition, if an application does not support connection multiplexing, the maximum number of concurrent requests is automatically set to 1.

option keep-conn

option keep-conn
no option keep-conn

Instruct the FastCGI application to keep the connection open or not after sending a response.

If disabled, the FastCGI application closes the connection after responding to this request. By default, this option is enabled.

option max-reqs <reqs>

option max-reqs <reqs>

Define the maximum number of concurrent requests this application will accept.

This option may be overwritten if the variable FCGI_MAX_REQS is retrieved during connection establishment. Furthermore, if the application does not support connection multiplexing, this option will be ignored. By default set to 1.

option mpxs-conns

option mpxs-conns
no option mpxs-conns

Enable or disable the support of connection multiplexing.

This option may be overwritten if the variable FCGI_MPXS_CONNS is retrieved during connection establishment. It is disabled by default.

set-param <name> <fmt> [ { if | unless } <condition> ]

set-param <name> <fmt> [ { if | unless } <condition> ]

Set a FastCGI parameter that should be passed to this application. Its value, defined by <fmt> must follows the Custom log format rules (see section 8.2.6 “Custom Log format”). It may optionally be followed by an ACL-based condition, in which case it will only be evaluated if the condition is true.

With this directive, it is possible to overwrite the value of default FastCGI parameters. If the value is evaluated to an empty string, the rule is ignored. These directives are evaluated in their declaration order.

Example:

# PHP only, required if PHP was built with --enable-force-cgi-redirect
set-param REDIRECT_STATUS 200

set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)]

10.1.2. Proxy section

use-fcgi-app <name> Define the FastCGI application to use for the backend.

Arguments:

<name>    is the name of the FastCGI application to use.

This keyword is only available for HTTP proxies with the backend capability and with at least one FastCGI server. However, FastCGI servers can be mixed with HTTP servers. But except there is a good reason to do so, it is not recommended (see section 10.3 about the limitations for details). Only one application may be defined at a time per backend.

Note that, once a FastCGI application is referenced for a backend, depending on the configuration some processing may be done even if the request is not sent to a FastCGI server. Rules to set parameters or pass headers to an application are evaluated.

10.1.3. Example

frontend front-http mode http bind *:80 bind *:

  use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ }
  default_backend back-static

backend back-static mode http server www A.B.C.D:80

backend back-dynamic mode http use-fcgi-app php-fpm server php-fpm A.B.C.D:9000 proto fcgi

fcgi-app php-fpm log-stderr global option keep-conn

  docroot /var/www/my-app
  index index.php
  path-info ^(/.+\.php)(/.*)?$

10.2. Default parameters

A Responder FastCGI application has the same purpose as a CGI/1.1 program. In the CGI/1.1 specification (RFC3875), several variables must be passed to the script. So HAProxy set them and some others commonly used by FastCGI applications. All these variables may be overwritten, with caution though.

  +-------------------+-----------------------------------------------------+
  | AUTH_TYPE         | Identifies the mechanism, if any, used by HAProxy   |
  |                   | to authenticate the user. Concretely, only the      |
  |                   | BASIC authentication mechanism is supported.        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | CONTENT_LENGTH    | Contains the size of the message-body attached to   |
  |                   | the request. It means only requests with a known    |
  |                   | size are considered as valid and sent to the        |
  |                   | application.                                        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | CONTENT_TYPE      | Contains the type of the message-body attached to   |
  |                   | the request. It may not be set.                     |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | DOCUMENT_ROOT     | Contains the document root on the remote host under |
  |                   | which the script should be executed, as defined in  |
  |                   | the application's configuration.                    |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy   |
  |                   | to communicate with the FastCGI application.        |
  |                   | Concretely, it is set to "CGI/1.1".                 |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | PATH_INFO         | Contains the portion of the URI path hierarchy      |
  |                   | following the part that identifies the script       |
  |                   | itself. To be set, the directive "path-info" must   |
  |                   | be defined.                                         |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | PATH_TRANSLATED   | If PATH_INFO is set, it is its translated version.  |
  |                   | It is the concatenation of DOCUMENT_ROOT and        |
  |                   | PATH_INFO. If PATH_INFO is not set, this parameters |
  |                   | is not set too.                                     |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | QUERY_STRING      | Contains the request's query string. It may not be  |
  |                   | set.                                                |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REMOTE_ADDR       | Contains the network address of the client sending  |
  |                   | the request.                                        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REMOTE_USER       | Contains the user identification string supplied by |
  |                   | client as part of user authentication.              |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REQUEST_METHOD    | Contains the method which should be used by the     |
  |                   | script to process the request.                      |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REQUEST_URI       | Contains the request's URI.                         |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SCRIPT_FILENAME   | Contains the absolute pathname of the script. it is |
  |                   | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SCRIPT_NAME       | Contains the name of the script. If the directive   |
  |                   | "path-info" is defined, it is the first part of the |
  |                   | URI path hierarchy, ending with the script name.    |
  |                   | Otherwise, it is the entire URI path.               |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_NAME       | Contains the name of the server host to which the   |
  |                   | client request is directed. It is the value of the  |
  |                   | header "Host", if defined. Otherwise, the           |
  |                   | destination address of the connection on the client |
  |                   | side.                                               |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_PORT       | Contains the destination TCP port of the connection |
  |                   | on the client side, which is the port the client    |
  |                   | connected to.                                       |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_PROTOCOL   | Contains the request's protocol.                    |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_SOFTWARE   | Contains the string "HAProxy" followed by the       |
  |                   | current HAProxy version.                            |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | HTTPS             | Set to a non-empty value ("on") if the script was   |
  |                   | queried through the HTTPS protocol.                 |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+

10.3. Limitations

The current implementation have some limitations. The first one is about the way some request headers are hidden to the FastCGI applications. This happens during the headers analysis, on the backend side, before the connection establishment. At this stage, HAProxy know the backend is using a FastCGI application but it don’t know if the request will be routed to a FastCGI server or not. But to hide request headers, it simply removes them from the HTX message. So, if the request is finally routed to an HTTP server, it never see these headers. For this reason, it is not recommended to mix FastCGI servers and HTTP servers under the same backend.

Similarly, the rules “set-param” and “pass-header” are evaluated during the request headers analysis. So the evaluation is always performed, even if the requests is finally forwarded to an HTTP server.

About the rules “set-param”, when a rule is applied, a pseudo header is added into the HTX message. So, the same way than for HTTP header rewrites, it may fail if the buffer is full. The rules “set-param” will compete with “http-request” ones.

Finally, all FastCGI params and HTTP headers are sent into a unique record FCGI_PARAM. Encoding of this record must be done in one pass, otherwise a processing error is returned. It means the record FCGI_PARAM, once encoded, must not exceeds the size of a buffer. However, there is no reserve to respect here.