0N/A<?xml version="1.0"?>

1472N/A<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">

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

0N/A

0N/A

0N/A<modulesynopsis metafile="mod_proxy_fcgi.xml.meta">

0N/A

0N/A<name>mod_proxy_fcgi</name>

0N/A<description>FastCGI support module for

0N/A<module>mod_proxy</module></description>

0N/A<status>Extension</status>

0N/A<sourcefile>mod_proxy_fcgi.c</sourcefile>

0N/A<identifier>proxy_fcgi_module</identifier>

0N/A<compatibility>Available in version 2.3 and later</compatibility>

0N/A

0N/A<summary>

0N/A <p>This module <em>requires</em> the service of <module

0N/A >mod_proxy</module>. It provides support for the

0N/A <a href="http://www.fastcgi.com/">FastCGI</a> protocol.</p>

0N/A

0N/A <p>Thus, in order to get the ability of handling the <code>FastCGI</code>

0N/A protocol, <module>mod_proxy</module> and

0N/A <module>mod_proxy_fcgi</module> have to be present in the server.</p>

0N/A

0N/A <p>Unlike <a href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a>

0N/A and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,

0N/A <module>mod_proxy_fcgi</module> has no provision for starting the

0N/A application process; <program>fcgistarter</program> is provided

0N/A (on some platforms) for that purpose. Alternatively, external launching

0N/A or process management may be available in the FastCGI application

0N/A framework in use.</p>

0N/A

0N/A <note type="warning"><title>Warning</title>

0N/A <p>Do not enable proxying until you have <a

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

0N/A servers are dangerous both to your network and to the Internet at

0N/A large.</p>

0N/A </note>

0N/A</summary>

0N/A

0N/A<seealso><program>fcgistarter</program></seealso>

0N/A<seealso><module>mod_proxy</module></seealso>

0N/A

0N/A<section id="examples"><title>Examples</title>

0N/A <p>Remember, in order to make the following examples work, you have to

0N/A enable <module>mod_proxy</module> and <module>mod_proxy_fcgi</module>.</p>

0N/A

0N/A <example><title>Single application instance</title>

0N/A <highlight language="config">

0N/A ProxyPass /myapp/ fcgi://localhost:4000/

0N/A </highlight>

0N/A </example>

0N/A

0N/A <p>This application should be able to handle multiple concurrent

0N/A connections. <module>mod_proxy</module> enables connection reuse by

0N/A default, so after a request has been completed the connection will be

0N/A held open by that httpd child process and won't be reused until that

0N/A httpd process routes another request to the application. If the

0N/A FastCGI application is unable to handle enough concurrent connections

0N/A from httpd, requests can block waiting for the application to close

0N/A an existing connection. One way to resolve this is to disable connection

0N/A reuse on the <directive>ProxyPass</directive> directive, as shown in

0N/A the following example:</p>

0N/A

0N/A <example><title>Single application instance, no connection reuse</title>

0N/A <highlight language="config">

0N/A ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=on

0N/A </highlight>

0N/A </example>

0N/A

0N/A <p> The following example passes the request URI as a filesystem

0N/A path for the PHP-FPM daemon to run. The request URL is implicitly added

0N/A to the 2nd parameter. The hostname and port following fcgi:// are where

0N/A PHP-FPM is listening.</p>

0N/A <example><title>PHP-FPM</title>

0N/A <highlight language="config">

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

0N/A </highlight>

0N/A </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 fci:// 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>

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

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

</p>

<highlight language="config">

&lt;FilesMatch \.php$&gt;

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

&lt;/FilesMatch&gt;

</highlight>

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

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