HAProxy Enterprise Documentation 2.0r1

FastCGI

A variation on the earlier Common Gateway Interface (CGI), FastCGI's main objective is to reduce the overhead related to interfacing between the Web server and CGI programs, thus allowing a server to handle more web page requests in less time. HAProxy Enterprise can send HTTP requests to Responder FastCGI applications.

HAProxy Enterprise implements all the features of the FastCGI specification for the Responder application, including the ability to multiplex several requests on a simple connection.

Set up FastCGI

  1. Add a fcgi-app section to your HAProxy Enterprise configuration. This section declares how to connect to the FastCGI application. See below for information about each directive.

    fcgi-app php-fpm
       log-stderr global
       option keep-conn
       docroot /var/www/my-app
       index index.php
       path-info ^(/.+\.php)(/.*)?$
  2. Add a backend section that lists the servers hosting the FastCGI application. The use-fcgi-app directive refers to the fcgi-app section you defined in the previous step. Each server line sets its proto field to fcgi:

    backend fcgi-servers
       mode http
       use-fcgi-app php-fpm
       server s1 192.168.0.10:9000 proto fcgi
       server s2 192.168.0.11:9000 proto fcgi
  3. Optionally, route requests for dynamic content to this backend. For example, the following frontend section uses the use_backend directive to route PHP requests to the FastCGI servers:

    frontend www
       mode http
       bind :80
       use_backend fcgi-servers if { path_end .php }
       default_backend static-file-servers

fcgi-app section

In the fcgi-app section, define the following directives:

Directive

Description

fcgi-app <name>

Declares a FastCGI application called <name>. To be valid, you must define at least the document root.

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

Declares or completes an access control list. See ACL usage for details. ACLs defined for a FastCGI application are private; no other application or proxy can use them.

In the same way, FastCGI applications cannot use any ACLs defined in any other section. Pre-defined ACLs are available.

docroot <path>

Defines the document root on the remote host. The parameter <path> serves to build the default value of FastCGI parameters SCRIPT_FILENAME and PATH_TRANSLATED. It is a mandatory setting.

index <script-name>

Defines the script name to append after a URI that ends with a slash ("/") to set the default value for the FastCGI parameter SCRIPT_NAME. It is an optional setting.

index index.php

log-stderr global, log-stderr <address> [len <length>] [format <format>] [sample <ranges>:<smp_size>] <facility> [<level> [<minlevel>]]

Enables logging of STDERR messages that the FastCGI application reports.

It is an optional setting. By default, HAProxy Enterprise ignores STDERR messages.

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

Specifies the name of a request header to pass to the FastCGI application.

Optionally, you can follow it with an ACL-based condition, in which case the FastCGI application evaluates it only if the condition is true.

Most request headers are already available to the FastCGI application with the prefix "HTTP". Thus, you only need this directive 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" never pass to the FastCGI application because they are already converted into parameters.

path-info <regex>

Defines a regular expression to extract the script-name and the path-info from the URI. Thus, <regex> must have two captures: the first to capture the script name, and the second to capture the path- info.

It is an optional setting. If not defined, it does not perform matching on the URI, and does not fill the FastCGI parameters PATH_INFO and PATH_TRANSLATED.

path-info ^(/.+\.php)(/.*)?$

option get-values, no option get-values

Enables or disables the retrieval of variables related to connection management.

HAproxy Enterprise can send the record FCGI_GET_VALUES upon connection establishment to retrieve the value for the following variables:

  • FCGI_MAX_REQS: The maximum number of concurrent requests this application can accept.

  • FCGI_MPXS_CONNS: "0" if this application does not multiplex connections; "1" otherwise.

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

    Note

    The maximum number of concurrent requests that a FastCGI application accepts is a connection variable. It only limits the number of streams per connection. If you must limit the global load on the application, you must set the server parameters "maxconn" and "pool-max-conn". Also, if an application does not support connection multiplexing, then the maximum number of concurrent requests automatically sets to 1.

option keep-conn, no option keep-conn

Tells the FastCGI application whether or not to keep the connection open after it sends a response. If disabled, the FastCGI application closes the connection after responding to this request. Default: enabled

option max-reqs <reqs>

Defines the maximum number of concurrent requests this application can accept. If the FastCGI application retrieves the variable FCGI_MAX_REQS during connection establishment, it can override this option. Furthermore, if the application does not do multiplexing, it will ignore this option. Default: 1

option mpxs-conns, no option mpxs-conns

Enables or disables the support of connection multiplexing. If the FastCGI application retrieves the variable FCGI_MPXS_CONNS during connection establishment, it can override this option. Default: disabled.

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

Sets a FastCGI parameter to pass to this application. Its value, defined by <fmt> can take a formatted string, the same as the log directive. Optionally, you can follow it with an ACL-based condition, in which case the FastCGI application evaluates it only if the condition is true.

With this directive, it is possible to overwrite the value of default FastCGI parameters. If the value evaluates to an empty string, it ignores the rule. The FastCGI application evaluates these directives in their declaration order.

# 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)]

Proxy section

In the proxy section of the configuration file, set up the following directives:

Directive

Description

use-fcgi-app <name>

Defines the name of the FastCGI application to use for the backend.

This keyword is only available for HTTP proxies with backend capability and at least one FastCGI server. However, you can mix FastCGI servers with HTTP servers, although we do not recommend doing this unless there is a good reason to do so (see Limitations below for details). You can define only one application at a time for each backend.

Note

Once you reference a FastCGI application for a backend, depending on the configuration, some processing may take place even if the request does not go to a FastCGI server. The backend evaluates rules to set parameters or pass headers to an application.

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 pass to the script. HAProxy Enterprise sets these variables as well as certain others that FastCGI applications commonly use.

You can overwrite all of these variables with extreme caution.

Parameter

Description

AUTH_TYPE

Identifies the mechanism, if any, that HAProxy Enterprise uses to authenticate the user. Concretely, we only support the BASIC authentication mechanism.

CONTENT_LENTH

Contains the size of the message-body attached to the request. This means that it only considers requests with a known size as valid to send to the application.

CONTENT_TYPE

Contains the type of the message-body attached to the request. Set this parameter only if there is a content-type header in the request or if you explicitly set it in the application configuration using the set-param directive.

DOCUMENT_ROOT

Contains the document root on the remote host under which to execute the script as defined in the application configuration.

GATEWAY_INTERFACE

Contains the dialect of CGI that HAProxy Enterprise uees to communicate with the FastCGI application. Concretely, it is set to "CGI/1.1".

PATH_INFO

Contains the portion of the URI path hierarchy that follows the part that identifies the script itself. To set it, you define the directive path-info.

PATH_TRANSLATED

If you set PATH_INFO, this parameter is its translated version. It is the concatenation of DOCUMENT_ROOT and PATH_INFO. If PATH_INFO is not set, this parameter is also not set.

QUERY_STRING

Contains the query string of the request. Set this parameter only if there is a query-string type header in the request or if you explicitly set it in the application configuration using the set-param directive.

REMOTE_ADDR

Contains the network address of the client sending the request.

REMOTE_USER

Contains the user identification string that the client supplied as part of user authentication.

REQUEST_METHOD

Contains the method that the script must use to process the request.

REQUEST_URI

Contains the request 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 you define the directive path-info, this is the first part of the URI path hierarchy, and ends with the script name. Otherwise, it is the entire URI path.

SERVER_NAME

Contains the name of the server host where to direct the client request. It is the value of the header "Host" (if available). Otherwise, it is 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 where the client connects.

SERVER_PROTOCOL

Contains the request protocol.

HTTPS

Sets to a non-empty value ("on") if the script executed through the HTTPS protocol.

Limitations

The current implementation has the following limitations:

  • We recommended that you do not mix FastCGI servers and HTTP servers under the same backend. HAProxy Enterprise hides certain request headers from FastCGI applications, which could be detrimental to your HTTP servers. Also, HAProxy Enterprise evaluates the FastCGI rules set-param and pass-header, even if the request finally goes to an HTTP server.

  • When HAProxy Enterprise applies a set-param rule, it adds a pseudo header to the message. Similar to HTTP header rewrites, it may fail if the buffer is full. The set-param rules will compete with the http-request rules for buffer space.

  • All FastCGI parameters and HTTP headers go into a unique record FCGI_PARAM. Encoding of this record must happen in one pass, otherwise HAProxy Enterprise returns a processing error. This means that the record FCGI_PARAM, once encoded, must not exceed the size of the buffer. However, you can use the entire reserved buffer space intended for rewriting an HTTP message here. (See the tune.maxrewrite parameter in the global section for information about the reserved space.)


Next up

gRPC