Description: | FastCGI support module formod_proxy |
---|---|
Status: | Extension |
Module Identifier: | proxy_fcgi_module |
Source File: | mod_proxy_fcgi.c |
Compatibility: | Available in version 2.3 and later |
This modulerequires the service ofmod_proxy
. It provides support for theFastCGI protocol.
Thus, in order to get the ability of handling theFastCGI
protocol,mod_proxy
andmod_proxy_fcgi
have to be present in the server.
Unlikemod_fcgid andmod_fastcgi,mod_proxy_fcgi
has no provision for starting the application process;fcgistarter
is provided (on some platforms) for that purpose. Alternatively, external launching or process management may be available in the FastCGI application framework in use.
Do not enable proxying until you havesecured your server. Open proxy servers are dangerous both to your network and to the Internet at large.
Remember, in order to make the following examples work, you have to enablemod_proxy
andmod_proxy_fcgi
.
ProxyPass "/myapp/" "fcgi://localhost:4000/"
mod_proxy_fcgi
disables connection reuse by default, so after a request has been completed the connection will NOT be held open by that httpd child process and won't be reused. If the FastCGI application is able to handle concurrent connections from httpd, you can opt-in to connection reuse as shown in the following example:
ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on
Please keep in mind that PHP-FPM (at the time of writing, February 2018) uses a prefork model, namely each of its worker processes can handle one connection at the time.
By default mod_proxy (configured withenablereuse=on
) allows a connection pool ofThreadsPerChild
connections to the backend for each httpd process when using a threaded mpm (likeworker
orevent
), so the following use cases should be taken into account:
MaxRequestWorkers
connections to the FCGI backend.mod_http2
is implemented, there are additional h2 worker threads that may force the creation of other backend connections. The overall count of connections in the pools may raise to more thanMaxRequestWorkers
.The maximum number of PHP-FPM worker processes needs to be configured wisely, since there is the chance that they will all end up "busy" handling idle persistent connections, without any room for new ones to be established, and the end user experience will be a pile of HTTP request timeouts.
The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. The request URL is implicitly added to the 2nd parameter. The hostname and port following fcgi:// are where PHP-FPM is listening. Connection pooling/reuse is enabled.
ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
The following example passes the request URI as a filesystem path for the PHP-FPM daemon to run. In this case, PHP-FPM is listening on a unix domain socket (UDS). Requires 2.4.9 or later. With this syntax, the hostname and optional port following fcgi:// are ignored.
ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"
The balanced gateway needsmod_proxy_balancer
and at least one load balancer algorithm module, such asmod_lbmethod_byrequests
, in addition to the proxy modules listed above.mod_lbmethod_byrequests
is the default, and will be used for this example configuration.
ProxyPass "/myapp/" "balancer://myappcluster/"<Proxy "balancer://myappcluster/"> BalancerMember "fcgi://localhost:4000" BalancerMember "fcgi://localhost:4001"</Proxy>
You can also force a request to be handled as a reverse-proxy request, by creating a suitable Handler pass-through. The example configuration below will pass all requests for PHP scripts to the specified FastCGI server using reverse proxy. This feature is available in Apache HTTP Server 2.4.10 and later. For performance reasons, you will want to define aworker representing the same fcgi:// backend. The benefit of this form is that it allows the normal mapping of URI to filename to occur in the server, and the local filesystem result is passed to the backend. When FastCGI is configured this way, the server can calculate the most accurate PATH_INFO.
<FilesMatch "\.php$"> # Note: The only part that varies is /path/to/app.sock SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"</FilesMatch># Define a matching worker.# The part that is matched to the SetHandler is the part that# follows the pipe. If you need to distinguish, "localhost; can# be anything unique.<Proxy "fcgi://localhost/" enablereuse=on max=10></Proxy><FilesMatch ...> SetHandler "proxy:fcgi://localhost:9000"</FilesMatch><FilesMatch ...> SetHandler "proxy:balancer://myappcluster/"</FilesMatch>
In addition to the configuration directives that control the behaviour ofmod_proxy
, there are a number ofenvironment variables that control the FCGI protocol provider:
ProxyPass
orProxyPassMatch
,mod_proxy_fcgi
will not set thePATH_INFO environment variable. This allows the backend FCGI server to correctly determineSCRIPT_NAME andScript-URI and be compliant with RFC 3875 section 3.3. If instead you needmod_proxy_fcgi
to generate a "best guess" forPATH_INFO, set this env-var. This is a workaround for a bug in some FCGI implementations. This variable can be set to multiple values to tweak at how the best guess is chosen (In 2.4.11 and later only):Description: | Specify the type of backend FastCGI application |
---|---|
Syntax: | ProxyFCGIBackendType FPM|GENERIC |
Default: | ProxyFCGIBackendType FPM |
Context: | server config, virtual host, directory, .htaccess |
Status: | Extension |
Module: | mod_proxy_fcgi |
Compatibility: | Available in version 2.4.26 and later |
This directive allows the type of backend FastCGI application to bespecified. Some FastCGI servers, such as PHP-FPM, use historical quirks ofenvironment variables to identify the type of proxy server being used. Setthis directive to "GENERIC" if your non PHP-FPM application has troubleinterpreting environment variables such as SCRIPT_FILENAME or PATH_TRANSLATEDas set by the server.
One example of values that change based on the setting of this directive isSCRIPT_FILENAME. When usingmod_proxy_fcgi
historically,SCRIPT_FILENAME was prefixed with the string "proxy:fcgi://". This variable iswhat some generic FastCGI applications would read as their script input, butPHP-FPM would strip the prefix then remember it was talking to Apache. In2.4.21 through 2.4.25, this prefix was automatically stripped by the server,breaking the ability of PHP-FPM to detect and interoperate with Apache in somescenarios.
Description: | Allow variables sent to FastCGI servers to be fixed up |
---|---|
Syntax: | ProxyFCGISetEnvIfconditional-expression [!]environment-variable-name [value-expression] |
Context: | server config, virtual host, directory, .htaccess |
Status: | Extension |
Module: | mod_proxy_fcgi |
Compatibility: | Available in version 2.4.26 and later |
Just before passing a request to the configured FastCGI server, the core ofthe web server sets a number of environment variables based on details of thecurrent request. FastCGI programs often uses these environment variablesas inputs that determine what underlying scripts they will process, or whatoutput they directly produce.
Examples of noteworthy environment variables are:
This directive allows the environment variables above, or any others ofinterest, to be overridden. This directive is evaluated after the initialvalues for these variables are set, so they can be used as input into boththe condition expressions and value expressions.
Parameter syntax:
# A basic, unconditional overrideProxyFCGISetEnvIf "true" PATH_INFO "/example"# Use an environment variable in the valueProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"# Use captures in the conditions and backreferences in the replacementProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m|(/.*prefix)(\d+)(.*)|" PATH_TRANSLATED "$1$3"
VARIABLE
, preventing it from being sent to the FastCGI server:ProxyFCGISetEnvIf true !VARIABLEWhereas the following will erase any existingvalue of
VARIABLE
(by setting it to the empty string), but the emptyVARIABLE
will still be sent to the server:ProxyFCGISetEnvIf true VARIABLEThe CGI/1.1 specificationdoes not distinguish between a variable with an empty value and a variable that does not exist. However, many CGI and FastCGI implementations distinguish (or allow scripts to distinguish) between the two. The choice of which to use is dependent upon your implementation and your reason for modifying the variable.
Copyright 2025 The Apache Software Foundation.
Licensed under theApache License, Version 2.0.