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

<highlight language="config">

ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=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.</p>

<example><title>PHP-FPM</title>

<highlight language="config">

ProxyPassMatch ^/myapp/.*\.php(/.*)?$ fcgi://localhost:9000/var/www/

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

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.

</p>

<example><title>Proxy via Handler</title>

<highlight language="config">

&lt;FilesMatch \.php$&gt;

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

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