0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<?xml version="1.0"?>

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

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

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

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

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

722110c962e63af83151d807f722b0fd8b9fd34btakashi<name>mod_proxy_fcgi</name>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<description>FastCGI support module for

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<module>mod_proxy</module></description>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<status>Extension</status>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<sourcefile>mod_proxy_fcgi.c</sourcefile>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<identifier>proxy_fcgi_module</identifier>

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

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<summary>

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

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim >mod_proxy</module>. It provides support for the

629efd2575d82e4678778e408bf932685a021d70trawick <a href="http://www.fastcgi.com/">FastCGI</a> protocol.</p>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

629efd2575d82e4678778e408bf932685a021d70trawick <p>Thus, in order to get the ability of handling the <code>FastCGI</code>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi protocol, <module>mod_proxy</module> and

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

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

629efd2575d82e4678778e408bf932685a021d70trawick <p>Unlike <a href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a>

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,

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

a67030130b82fe3e5231adcaab8a6641bab764efcovener application process; <program>fcgistarter</program> is provided

a67030130b82fe3e5231adcaab8a6641bab764efcovener (on some platforms) for that purpose. Alternatively, external launching

a67030130b82fe3e5231adcaab8a6641bab764efcovener or process management may be available in the FastCGI application

a67030130b82fe3e5231adcaab8a6641bab764efcovener framework in use.</p>

629efd2575d82e4678778e408bf932685a021d70trawick

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi <note type="warning"><title>Warning</title>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi <p>Do not enable proxying until you have <a

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

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

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi large.</p>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi </note>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi</summary>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<seealso><program>fcgistarter</program></seealso>

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi<seealso><module>mod_proxy</module></seealso>

629efd2575d82e4678778e408bf932685a021d70trawick

629efd2575d82e4678778e408bf932685a021d70trawick<section id="examples"><title>Examples</title>

629efd2575d82e4678778e408bf932685a021d70trawick <p>Remember, in order to make the following examples work, you have to

629efd2575d82e4678778e408bf932685a021d70trawick enable <module>mod_proxy</module> and <module>mod_proxy_fcgi</module>.</p>

629efd2575d82e4678778e408bf932685a021d70trawick

af821737aacf3ed6f419732f7420b331bae80ba7trawick <example><title>Single application instance</title>

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh <highlight language="config">

629efd2575d82e4678778e408bf932685a021d70trawick ProxyPass /myapp/ fcgi://localhost:4000/

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh </highlight>

629efd2575d82e4678778e408bf932685a021d70trawick </example>

629efd2575d82e4678778e408bf932685a021d70trawick

4472df9a373740420f81c4c14a331b54d2f91603covener <p> <module>mod_proxy_fcgi</module> disables connection reuse by

4472df9a373740420f81c4c14a331b54d2f91603covener default, so after a request has been completed the connection will NOT be

4472df9a373740420f81c4c14a331b54d2f91603covener held open by that httpd child process and won't be reused. If the

4472df9a373740420f81c4c14a331b54d2f91603covener FastCGI application is able to handle concurrent connections

4472df9a373740420f81c4c14a331b54d2f91603covener from httpd, you can opt-in to connection reuse as shown in the following

4472df9a373740420f81c4c14a331b54d2f91603covener example:</p>

4472df9a373740420f81c4c14a331b54d2f91603covener

4472df9a373740420f81c4c14a331b54d2f91603covener <example><title>Single application instance, connection reuse</title>

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh <highlight language="config">

4472df9a373740420f81c4c14a331b54d2f91603covener ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=off

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh </highlight>

af821737aacf3ed6f419732f7420b331bae80ba7trawick </example>

af821737aacf3ed6f419732f7420b331bae80ba7trawick

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener <p> The following example passes the request URI as a filesystem

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener path for the PHP-FPM daemon to run. The request URL is implicitly added

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener to the 2nd parameter. The hostname and port following fcgi:// are where

4472df9a373740420f81c4c14a331b54d2f91603covener PHP-FPM is listening. Connection pooling is enabled.</p>

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

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener <highlight language="config">

4472df9a373740420f81c4c14a331b54d2f91603covener ProxyPassMatch ^/myapp/.*\.php(/.*)?$ fcgi://localhost:9000/var/www/ disablereuse=off

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener </highlight>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener </example>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener <p> The following example passes the request URI as a filesystem

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener path for the PHP-FPM daemon to run. In this case, PHP-FPM is listening on

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener a unix domain socket (UDS). Requires 2.4.9 or later. With this syntax,

d13dc5eaf2353e4a5f308d3f87f1e18c3b03a278lgentis the hostname and optional port following fcgi:// are ignored.</p>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener <example><title>PHP-FPM with UDS</title>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener <highlight language="config">

4472df9a373740420f81c4c14a331b54d2f91603covener # UDS does not currently support connection reuse

4472df9a373740420f81c4c14a331b54d2f91603covener ProxyPassMatch ^/(.*\.php(/.*)?)$ "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener </highlight>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener </example>

193b3e56c39bd0833fe0ab3cb44503839d1d9164covener

fd961f7871d2a909f75baf2769652e59c360f16etrawick <p>The balanced gateway needs <module>mod_proxy_balancer</module> and

860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim at least one load balancer algorithm module, such as

fd961f7871d2a909f75baf2769652e59c360f16etrawick <module>mod_lbmethod_byrequests</module>, in addition to the proxy

fd961f7871d2a909f75baf2769652e59c360f16etrawick modules listed above. <module>mod_lbmethod_byrequests</module> is the

af821737aacf3ed6f419732f7420b331bae80ba7trawick default, and will be used for this example configuration.</p>

629efd2575d82e4678778e408bf932685a021d70trawick

af821737aacf3ed6f419732f7420b331bae80ba7trawick <example><title>Balanced gateway to multiple application instances</title>

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh <highlight language="config">

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedoohProxyPass /myapp/ balancer://myappcluster/

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

49c1d45abbd5add003287667aa1e934444fa4974rjung BalancerMember fcgi://localhost:4000

49c1d45abbd5add003287667aa1e934444fa4974rjung BalancerMember fcgi://localhost:4001

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh&lt;/Proxy&gt;

626cbbae0d87d1e58fabf969ef6c55e3f5fcd544humbedooh </highlight>

629efd2575d82e4678778e408bf932685a021d70trawick </example>

eb8a9708b915f27a3a10c8fc78e001f401186041covener

eb8a9708b915f27a3a10c8fc78e001f401186041covener <p>You can also force a request to be handled as a reverse-proxy

eb8a9708b915f27a3a10c8fc78e001f401186041covener request, by creating a suitable Handler pass-through. The example

eb8a9708b915f27a3a10c8fc78e001f401186041covener configuration below will pass all requests for PHP scripts to the

3f178abd1c04c62348323619be84a5bd1fe1c3a2covener specified FastCGI server using reverse proxy.

3f178abd1c04c62348323619be84a5bd1fe1c3a2covener This feature is available in Apache HTTP Server 2.4.10 and later. For performance

3f178abd1c04c62348323619be84a5bd1fe1c3a2covener reasons, you will want to define a <a href="/mod_proxy.html#worker">worker</a>

3f178abd1c04c62348323619be84a5bd1fe1c3a2covener representing the same fcgi:// backend. The benefit of this form is that it

3f178abd1c04c62348323619be84a5bd1fe1c3a2covener allows the normal mapping of URI to filename to occur in the server, and the

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener local filesystem result is passed to the backend. When FastCGI is

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener configured this way, the server can calculate the most accurate

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener PATH_INFO.

eb8a9708b915f27a3a10c8fc78e001f401186041covener </p>

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

eb8a9708b915f27a3a10c8fc78e001f401186041covener <highlight language="config">

eb8a9708b915f27a3a10c8fc78e001f401186041covener&lt;FilesMatch \.php$&gt;

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

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

eb8a9708b915f27a3a10c8fc78e001f401186041covener&lt;/FilesMatch&gt;

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener&lt;FilesMatch ...&gt;

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

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener&lt;/FilesMatch&gt;

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener&lt;FilesMatch ...&gt;

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener SetHandler "proxy:balancer://myappcluster/"

e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66covener&lt;/FilesMatch&gt;

eb8a9708b915f27a3a10c8fc78e001f401186041covener </highlight>

eb8a9708b915f27a3a10c8fc78e001f401186041covener </example>

629efd2575d82e4678778e408bf932685a021d70trawick</section>

629efd2575d82e4678778e408bf932685a021d70trawick

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

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

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

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

2935c06515b172db47bc622218179a22fa45437ejim provider:</p>

2935c06515b172db47bc622218179a22fa45437ejim <dl>

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

2935c06515b172db47bc622218179a22fa45437ejim <dd>By default <module>mod_proxy_fcgi</module> will neither create

2935c06515b172db47bc622218179a22fa45437ejim nor export the <var>PATH_INFO</var> environment variable. This allows

2935c06515b172db47bc622218179a22fa45437ejim the backend FCGI server to correctly determine <var>SCRIPT_NAME</var>

2935c06515b172db47bc622218179a22fa45437ejim and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.

2935c06515b172db47bc622218179a22fa45437ejim If instead you need <module>mod_proxy_fcgi</module> to generate

2935c06515b172db47bc622218179a22fa45437ejim a "best guess" for <var>PATH_INFO</var>, set this env-var.

2935c06515b172db47bc622218179a22fa45437ejim This is a workaround for a bug in some FCGI implementations.</dd>

2935c06515b172db47bc622218179a22fa45437ejim </dl>

2935c06515b172db47bc622218179a22fa45437ejim</section>

2935c06515b172db47bc622218179a22fa45437ejim

0efb708c6ae04a014ab52b50fb0b3961473296d3takashi</modulesynopsis>