<summary>
<p>This module <em>requires</em> the service of <module
- >mod_proxy</module>. It provides support for the
+ >mod_proxy</module>. It provides support for the
<a href="http://www.fastcgi.com/">FastCGI</a> protocol.</p>
<p>Thus, in order to get the ability of handling the <code>FastCGI</code>
<module>mod_proxy_fcgi</module> have to be present in the server.</p>
<p>Unlike <a href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a>
- and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,
+ and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,
<module>mod_proxy_fcgi</module> has no provision for starting the
- application process; <program>fcgistarter</program> is provided for
- that purpose.</p>
+ application process; <program>fcgistarter</program> is provided
+ (on some platforms) for that purpose. Alternatively, external launching
+ or process management may be available in the FastCGI application
+ framework in use.</p>
<note type="warning"><title>Warning</title>
<p>Do not enable proxying until you have <a
<seealso><program>fcgistarter</program></seealso>
<seealso><module>mod_proxy</module></seealso>
+<seealso><module>mod_authnz_fcgi</module></seealso>
<section id="examples"><title>Examples</title>
<p>Remember, in order to make the following examples work, you have to
enable <module>mod_proxy</module> and <module>mod_proxy_fcgi</module>.</p>
<example><title>Single application instance</title>
- ProxyPass /myapp/ fcgi://localhost:4000/
+ <highlight language="config">
+ProxyPass "/myapp/" "fcgi://localhost:4000/"
+ </highlight>
</example>
- <p>This application should be able to handle multiple concurrent
- connections. <module>mod_proxy</module> enables connection reuse by
- default, so after a request has been completed the connection will be
- held open by that httpd child process and won't be reused until that
- httpd process routes another request to the application. If the
- FastCGI application is unable to handle enough concurrent connections
- from httpd, requests can block waiting for the application to close
- an existing connection. One way to resolve this is to disable connection
- reuse on the <directive>ProxyPass</directive> directive, as shown in
- the following example:</p>
-
- <example><title>Single application instance, no connection reuse</title>
- ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=on
+ <p> <module>mod_proxy_fcgi</module> 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:</p>
+
+ <example><title>Single application instance, connection reuse (2.4.11 and later)</title>
+ <highlight language="config">
+ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on
+ </highlight>
+ </example>
+
+ <p> 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 is enabled.</p>
+ <example><title>PHP-FPM</title>
+ <highlight language="config">
+ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
+ </highlight>
+ </example>
+
+ <p> 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.</p>
+ <example><title>PHP-FPM with UDS</title>
+ <highlight language="config">
+# UDS does not currently support connection reuse
+ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"
+ </highlight>
</example>
<p>The balanced gateway needs <module>mod_proxy_balancer</module> and
- at least one load balancer algorithm module, such as
+ at least one load balancer algorithm module, such as
<module>mod_lbmethod_byrequests</module>, in addition to the proxy
modules listed above. <module>mod_lbmethod_byrequests</module> is the
default, and will be used for this example configuration.</p>
<example><title>Balanced gateway to multiple application instances</title>
- ProxyPass /myapp/ balancer://myappcluster/<br />
- <Proxy balancer://myappcluster/><br />
- <indent>
- BalancerMember fcgi://localhost:4000/<br />
- BalancerMember fcgi://localhost:4001/<br />
- </indent>
- </Proxy>
+ <highlight language="config">
+ProxyPass "/myapp/" "balancer://myappcluster/"
+<Proxy "balancer://myappcluster/">
+ BalancerMember "fcgi://localhost:4000"
+ BalancerMember "fcgi://localhost:4001"
+</Proxy>
+ </highlight>
</example>
+
+ <p>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 a <a href="mod_proxy.html#workers">worker</a>
+ 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.
+ </p>
+ <example><title>Proxy via Handler</title>
+ <highlight language="config">
+<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>
+ </highlight>
+ </example>
</section>
<section id="env"><title>Environment Variables</title>
provider:</p>
<dl>
<dt>proxy-fcgi-pathinfo</dt>
- <dd>By default <module>mod_proxy_fcgi</module> will neither create
- nor export the <var>PATH_INFO</var> environment variable. This allows
+ <dd>When configured via <directive module="mod_proxy"
+ >ProxyPass</directive> or <directive module="mod_proxy"
+ >ProxyPassMatch</directive>, <module>mod_proxy_fcgi</module> will not
+ set the <var>PATH_INFO</var> environment variable. This allows
the backend FCGI server to correctly determine <var>SCRIPT_NAME</var>
and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.
If instead you need <module>mod_proxy_fcgi</module> to generate
a "best guess" for <var>PATH_INFO</var>, set this env-var.
- This is a workaround for a bug in some FCGI implementations.</dd>
+ 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):
+ <dl>
+ <dt>first-dot</dt>
+ <dd>PATH_INFO is split from the slash following the
+ <em>first</em> "." in the URL.</dd>
+ <dt>last-dot</dt>
+ <dd>PATH_INFO is split from the slash following the
+ <em>last</em> "." in the URL.</dd>
+ <dt>full</dt>
+ <dd>PATH_INFO is calculated by an attempt to map the URL to the
+ local filesystem.</dd>
+ <dt>unescape</dt>
+ <dd>PATH_INFO is the path component of the URL, unescaped /
+ decoded.</dd>
+ <dt>any other value</dt>
+ <dd>PATH_INFO is the same as the path component of the URL.
+ Originally, this was the only proxy-fcgi-pathinfo option.</dd>
+ </dl>
+ </dd>
</dl>
</section>
+<directivesynopsis>
+<name>ProxyFCGIBackendType</name>
+<description>Specify the type of backend FastCGI application</description>
+<syntax>ProxyFCGIBackendType FPM|GENERIC</syntax>
+<default>ProxyFCGIBackendType FPM</default>
+<contextlist><context>server config</context>
+<context>virtual host</context><context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>FileInfo</override>
+<compatibility>Available in version 2.4.26 and later</compatibility>
+
+<usage>
+<p>This directive allows the type of backend FastCGI application to be
+specified. Some FastCGI servers, such as PHP-FPM, use historical quirks of
+environment variables to identify the type of proxy server being used. Set
+this directive to "GENERIC" if your non PHP-FPM application has trouble
+interpreting environment variables such as SCRIPT_FILENAME or PATH_TRANSLATED
+as set by the server.</p>
+
+<p>One example of values that change based on the setting of this directive is
+SCRIPT_FILENAME. When using <module>mod_proxy_fcgi</module> historically,
+SCRIPT_FILENAME was prefixed with the string "proxy:fcgi://". This variable is
+what some generic FastCGI applications would read as their script input, but
+PHP-FPM would strip the prefix then remember it was talking to Apache. In
+2.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 some
+scenarios.</p>
+</usage>
+</directivesynopsis>
+
+<directivesynopsis>
+<name>ProxyFCGISetEnvIf</name>
+<description>Allow variables sent to FastCGI servers to be fixed up</description>
+<syntax>ProxyFCGISetEnvIf <var>conditional-expression</var>
+ [!]<var>environment-variable-name</var>
+ [<var>value-expression</var>]</syntax>
+<contextlist><context>server config</context>
+<context>virtual host</context><context>directory</context>
+<context>.htaccess</context></contextlist>
+<override>FileInfo</override>
+<compatibility>Available in version 2.4.26 and later</compatibility>
+
+<usage>
+<p>Just before passing a request to the configured FastCGI server, the core of
+the web server sets a number of environment variables based on details of the
+current request. FastCGI programs often uses these environment variables
+as inputs that determine what underlying scripts they will process, or what
+output they directly produce.</p>
+<p>Examples of noteworthy environment variables are:</p>
+<ul>
+ <li>SCRIPT_NAME</li>
+ <li>SCRIPT_FILENAME</li>
+ <li>REQUEST_URI</li>
+ <li>PATH_INFO</li>
+ <li>PATH_TRANSLATED</li>
+</ul>
+
+<p>This directive allows the environment variables above, or any others of
+interest, to be overridden. This directive is evaluated after the initial
+values for these variables are set, so they can be used as input into both
+the condition expressions and value expressions.</p>
+<p>Parameter syntax:</p>
+<dl>
+<dt>conditional-expression</dt>
+<dd>Specifies an expression that controls whether the environment variable that
+ follows will be modified. For information on the expression syntax, see
+ the examples that follow or the full specification at the
+ <a href="../expr.html">ap_expr</a> documentation.
+ </dd>
+<dt>environment-variable-name</dt>
+<dd> Specifies the CGI environment variable to change,
+ such as PATH_INFO. If preceded by an exclamation point, the variable
+ will be unset.</dd>
+<dt>value-expression</dt>
+<dd>Specifies the replacement value for the preceding environment variable.
+ Backreferences, such as "$1", can be included from regular expression
+ captures in <var>conditional-expression</var>. If omitted, the variable is
+ set (or overridden) to an empty string — but see the Note below.</dd>
+</dl>
+
+<example>
+ <highlight language="config">
+# A basic, unconditional override
+ProxyFCGISetEnvIf "true" PATH_INFO "/example"
+
+# Use an environment variable in the value
+ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
+
+# Use captures in the conditions and backreferences in the replacement
+ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m|(/.*prefix)(\d+)(.*)|" PATH_TRANSLATED "$1$3"
+ </highlight>
+</example>
+
+<note><title>Note: Unset vs. Empty</title>
+ The following will unset <code>VARIABLE</code>, preventing it from being sent
+ to the FastCGI server:
+
+ <highlight language="config">ProxyFCGISetEnvIf true !VARIABLE</highlight>
+
+ Whereas the following will erase any existing <em>value</em> of
+ <code>VARIABLE</code> (by setting it to the empty string), but the empty
+ <code>VARIABLE</code> will still be sent to the server:
+
+ <highlight language="config">ProxyFCGISetEnvIf true VARIABLE</highlight>
+
+ The CGI/1.1 specification
+ <a href="https://tools.ietf.org/html/rfc3875#section-4.1">does not
+ distinguish</a> 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.
+</note>
+
+</usage>
+</directivesynopsis>
+
</modulesynopsis>
projects / apache / blobdiff