MINOR: doc: Add documentation about the FastCGI support
diff --git a/doc/configuration.txt b/doc/configuration.txt
index 34fff1d..e5a2497 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -113,7 +113,16 @@
9.2. HTTP compression
9.3. Stream Processing Offload Engine (SPOE)
9.4. Cache
+9.5. fcgi-app
+10. FastCGI applications
+10.1. Setup
+10.1.1. Fcgi-app section
+10.1.2. Proxy section
+10.1.3. Example
+10.2. Default parameters
+10.3. Limitations
+
1. Quick reminder about HTTP
----------------------------
@@ -2551,6 +2560,7 @@
unique-id-format X X X -
unique-id-header X X X -
use_backend - X X -
+use-fcgi-app - - X X
use-server - - X X
------------------------------------+----------+----------+---------+---------
keyword defaults frontend listen backend
@@ -10472,6 +10482,14 @@
See also: "default_backend", "tcp-request", "fullconn", "log-format", and
section 7 about ACLs.
+use-fcgi-app <name>
+ Defines the FastCGI application to use for the backend.
+ May be used in sections : defaults | frontend | listen | backend
+ no | no | yes | yes
+ Arguments :
+ <name> is the name of the FastCGI application to use.
+
+ See section 10.1 about FastCGI application setup for details.
use-server <server> if <condition>
use-server <server> unless <condition>
@@ -17854,14 +17872,16 @@
The HTTP compression has been moved in a filter in HAProxy 1.7. "compression"
keyword must still be used to enable and configure the HTTP compression. And
-when no other filter is used, it is enough. When used with the cache enabled,
-it is also enough. In this case, the compression is always done after the
-response is stored in the cache. But it is mandatory to explicitly use a filter
-line to enable the HTTP compression when at least one filter other than the
-cache is used for the same listener/frontend/backend. This is important to know
-the filters evaluation order.
+when no other filter is used, it is enough. When used with the cache or the
+fcgi-app enabled, it is also enough. In this case, the compression is always
+done after the response is stored in the cache. But it is mandatory to
+explicitly use a filter line to enable the HTTP compression when at least one
+filter other than the cache or the fcgi-app is used for the same
+listener/frontend/backend. This is important to know the filters evaluation
+order.
-See also : "compression" and section 9.4 about the cache filter.
+See also : "compression", section 9.4 about the cache filter and section 9.5
+ about the fcgi-app filter.
9.3. Stream Processing Offload Engine (SPOE)
@@ -17907,14 +17927,356 @@
The cache uses a filter to store cacheable responses. The HTTP rules
"cache-store" and "cache-use" must be used to define how and when to use a
cache. By default the corresponding filter is implicitly defined. And when no
-other filters than cache or compression are used, it is enough. In such case,
-the compression filter is always evaluated after the cache filter. But it is
-mandatory to explicitly use a filter line to use a cache when at least one
-filter other than the compression is used for the same
+other filters than fcgi-app or compression are used, it is enough. In such
+case, the compression filter is always evaluated after the cache filter. But it
+is mandatory to explicitly use a filter line to use a cache when at least one
+filter other than the compression or the fcgi-app is used for the same
listener/frontend/backend. This is important to know the filters evaluation
order.
+See also : section 9.2 about the compression filter, section 9.5 about the
+ fcgi-app filter and section 6 about cache.
+
+
+9.5. Fcgi-app
+-------------
+
+filter fcg-app <name>
+
+ Arguments :
+
+ <name> is name of the fcgi-app section this filter will use.
+
+The FastCGI application uses a filter to evaluate all custom parameters on the
+request path, and to process the headers on the response path. the <name> must
+reference an existing fcgi-app section. The directive "use-fcgi-app" should be
+used to define the application to use. By default the corresponding filter is
+implicitly defined. And when no other filters than cache or compression are
+used, it is enough. But it is mandatory to explicitly use a filter line to a
+fcgi-app when at least one filter other than the compression or the cache is
+used for the same backend. This is important to know the filters evaluation
+order.
+
+See also: "use-fcgi-app", section 9.2 about the compression filter, section 9.4
+ about the cache filter and section 10 about FastCGI application.
+
+
+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>
+ Declare a FastCGI application named <name>. To be valid, at least the
+ document root must be defined.
+
+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>
+ 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>
+ 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 <address> [len <length>] [format <format>]
+ [sample <ranges>:<smp_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> ]
+ 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>
+ Define a regular expression to extract the script-name and the path-info
+ from the URI. Thus, <regex> should have two captures: the first one to
+ capture the script name and the second one to capture the path-info. It is an
+ optional setting. If it is not defined, no matching is performed on the
+ URI. and the FastCGI parameters PATH_INFO and PATH_TRANSLATED are not filled.
+
+ Example :
+ path-info ^(/.+\.php)(/.*)?$
+
+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 connexion 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
+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>
+ 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
+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 a FastCGI parameter that should be passed to this application. Its
+ value, defined by <fmt> must follows the log-format rules (see section 8.2.4
+ "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
+scipt. 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. |
+ | | |
+ +-------------------+-----------------------------------------------------+
+ | 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.
+
-See also : section 9.2 about the compression filter and section 6 about cache.
+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.
/*
* Local variables: