<?xml version="1.0"?>

<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<modulesynopsis metafile="mod_proxy_fcgi.xml.meta">

<name>mod_proxy_fcgi</name>

<description>FastCGI support module for

<module>mod_proxy</module></description>

<status>Extension</status>

<sourcefile>mod_proxy_fcgi.c</sourcefile>

<identifier>proxy_fcgi_module</identifier>

<compatibility>Available in version 2.3 and later</compatibility>

<summary>

<p>This module <em>requires</em> the service of <module

>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>

protocol, <module>mod_proxy</module> and

<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>,

<module>mod_proxy_fcgi</module> has no provision for starting the

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

href="mod_proxy.html#access">secured your server</a>. Open proxy

servers are dangerous both to your network and to the Internet at

large.</p>

</note>

</summary>

<seealso><program>fcgistarter</program></seealso>

<seealso><module>mod_proxy</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>

<highlight language="config">

ProxyPass /myapp/ fcgi://localhost:4000/

</highlight>

</example>

<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</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

<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>

<highlight language="config">

ProxyPass /myapp/ balancer://myappcluster/

&lt;Proxy balancer://myappcluster/&gt;

BalancerMember fcgi://localhost:4000

BalancerMember fcgi://localhost:4001

&lt;/Proxy&gt;

</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#worker">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">

&lt;FilesMatch \.php$&gt;

# Note: The only part that varies is /path/to/app.sock

SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"

&lt;/FilesMatch&gt;

# 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.

&lt;Proxy fcgi://localhost/ enablereuse=on max=10&gt;

&lt;/Proxy&gt;

&lt;FilesMatch ...&gt;

SetHandler "proxy:fcgi://localhost:9000"

&lt;/FilesMatch&gt;

&lt;FilesMatch ...&gt;

SetHandler "proxy:balancer://myappcluster/"

&lt;/FilesMatch&gt;

</highlight>

</example>

</section>

<section id="env"><title>Environment Variables</title>

<p>In addition to the configuration directives that control the

behaviour of <module>mod_proxy</module>, there are a number of

<dfn>environment variables</dfn> that control the FCGI protocol

provider:</p>

<dl>

<dt>proxy-fcgi-pathinfo</dt>

<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. This

variable can be set to multiple values to tweak at how the best guess

is chosen:

<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>

</modulesynopsis>