MINOR: doc: Add documentation about the FastCGI support
This commit is contained in:
Christopher Faulet
parent
99eff65f4f
commit
b30b310f68
@ -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 <backend> [{if | unless} <condition>]
|
||||
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 @@ 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 <name>
|
||||
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 <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.
|
||||
|
||||
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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user