From: Christopher Faulet Date: Thu, 12 Sep 2019 21:03:09 +0000 (+0200) Subject: MINOR: doc: Add documentation about the FastCGI support X-Git-Tag: v2.1-dev2~63 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b30b310f68d1ce34a96117e018b72d912b4d4691;p=thirdparty%2Fhaproxy.git MINOR: doc: Add documentation about the FastCGI support --- diff --git a/doc/configuration.txt b/doc/configuration.txt index 34fff1d78b..e5a249736d 100644 --- a/doc/configuration.txt +++ b/doc/configuration.txt @@ -113,6 +113,15 @@ Summary 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 @@ transparent (deprecated) X - X X 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 @@ use_backend [{if | unless} ] See also: "default_backend", "tcp-request", "fullconn", "log-format", and section 7 about ACLs. +use-fcgi-app + Defines the FastCGI application to use for the backend. + May be used in sections : defaults | frontend | listen | backend + no | no | yes | yes + Arguments : + is the name of the FastCGI application to use. + + See section 10.1 about FastCGI application setup for details. use-server if use-server unless @@ -17854,14 +17872,16 @@ filter compression 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 @@ filter cache 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 and section 6 about cache. +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 + + Arguments : + + 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 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 + Declare a FastCGI application named . To be valid, at least the + document root must be defined. + +acl [flags] [operator] ... + 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 + Define the document root on the remote host. will be used to build + the default value of FastCGI parameters SCRIPT_FILENAME and + PATH_TRANSLATED. It is a mandatory setting. + +index + 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
[len ] [format ] + [sample :] [ []] + 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 [ { if | unless } ] + 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 + Define a regular expression to extract the script-name and the path-info + from the URI. Thus, 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 + 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 [ { if | unless } ] + Set a FastCGI parameter that should be passed to this application. Its + value, defined by 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 + Define the FastCGI application to use for the backend. + + Arguments : + 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. + +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: