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

&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>By default <module>mod_proxy_fcgi</module> will neither create

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

</dl>

</section>

</modulesynopsis>