mod_proxy_fcgi.xml revision e9dfd8bc94d903cbe69bc4d6f6ec8c42b45b4d66
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<!-- $LastChangedRevision$ -->
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder Licensed to the Apache Software Foundation (ASF) under one or more
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder contributor license agreements. See the NOTICE file distributed with
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder this work for additional information regarding copyright ownership.
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder The ASF licenses this file to You under the Apache License, Version 2.0
d21dd452cd68abade683103a5c0cfe6d02c5f17bTill Mossakowski (the "License"); you may not use this file except in compliance with
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder the License. You may obtain a copy of the License at
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder Unless required by applicable law or agreed to in writing, software
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski See the License for the specific language governing permissions and
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder limitations under the License.
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder<modulesynopsis metafile="mod_proxy_fcgi.xml.meta">
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder<description>FastCGI support module for
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder<compatibility>Available in version 2.3 and later</compatibility>
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski <p>This module <em>requires</em> the service of <module
56cd0da55d058b262b1626ddcd78db6bd9a90551Christian Maeder >mod_proxy</module>. It provides support for the
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder <a href="http://www.fastcgi.com/">FastCGI</a> protocol.</p>
c616e681da8c052b62e14247fea522da099ac0e4Christian Maeder <p>Thus, in order to get the ability of handling the <code>FastCGI</code>
38a1db3f9cedee9df49232bd524bcc82707480d5Christian Maeder <module>mod_proxy_fcgi</module> have to be present in the server.</p>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <p>Unlike <a href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski and <a href="http://www.fastcgi.com/">mod_fastcgi</a>,
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <module>mod_proxy_fcgi</module> has no provision for starting the
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski application process; <program>fcgistarter</program> is provided
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich (on some platforms) for that purpose. Alternatively, external launching
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski or process management may be available in the FastCGI application
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski framework in use.</p>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski <note type="warning"><title>Warning</title>
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski <p>Do not enable proxying until you have <a
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski href="mod_proxy.html#access">secured your server</a>. Open proxy
58b671de3fe578346fef9642ffa3c5a0a0edb3cbTill Mossakowski servers are dangerous both to your network and to the Internet at
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski<seealso><program>fcgistarter</program></seealso>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski<seealso><module>mod_proxy</module></seealso>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski<section id="examples"><title>Examples</title>
38a1db3f9cedee9df49232bd524bcc82707480d5Christian Maeder <p>Remember, in order to make the following examples work, you have to
38a1db3f9cedee9df49232bd524bcc82707480d5Christian Maeder enable <module>mod_proxy</module> and <module>mod_proxy_fcgi</module>.</p>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <example><title>Single application instance</title>
50ea34ea29d0121f3e692b7029b09d28dc7988fdTill Mossakowski ProxyPass /myapp/ fcgi://localhost:4000/
50ea34ea29d0121f3e692b7029b09d28dc7988fdTill Mossakowski <p>This application should be able to handle multiple concurrent
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski connections. <module>mod_proxy</module> enables connection reuse by
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski default, so after a request has been completed the connection will be
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski held open by that httpd child process and won't be reused until that
b0294d73dcefc502ddaa13e18b46103a5916971fTill Mossakowski httpd process routes another request to the application. If the
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski FastCGI application is unable to handle enough concurrent connections
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski from httpd, requests can block waiting for the application to close
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski an existing connection. One way to resolve this is to disable connection
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski reuse on the <directive>ProxyPass</directive> directive, as shown in
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski the following example:</p>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <example><title>Single application instance, no connection reuse</title>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder ProxyPass /myapp/ fcgi://localhost:4000/ disablereuse=on
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <p> The following example passes the request URI as a filesystem
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski path for the PHP-FPM daemon to run. The request URL is implicitly added
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski to the 2nd parameter. The hostname and port following fcgi:// are where
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski PHP-FPM is listening.</p>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski ProxyPassMatch ^/myapp/.*\.php(/.*)?$ fcgi://localhost:9000/var/www/
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski <p> The following example passes the request URI as a filesystem
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski path for the PHP-FPM daemon to run. In this case, PHP-FPM is listening on
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski a unix domain socket (UDS). Requires 2.4.9 or later. With this syntax,
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich the hostname and optional port following fcgi:// are ignored.</p>
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich ProxyPassMatch ^/(.*\.php(/.*)?)$ "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich <p>The balanced gateway needs <module>mod_proxy_balancer</module> and
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich at least one load balancer algorithm module, such as
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich <module>mod_lbmethod_byrequests</module>, in addition to the proxy
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich modules listed above. <module>mod_lbmethod_byrequests</module> is the
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich default, and will be used for this example configuration.</p>
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich <example><title>Balanced gateway to multiple application instances</title>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus LuettichProxyPass /myapp/ balancer://myappcluster/
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich<Proxy balancer://myappcluster/>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich BalancerMember fcgi://localhost:4000
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich BalancerMember fcgi://localhost:4001
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich</Proxy>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich <p>You can also force a request to be handled as a reverse-proxy
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich request, by creating a suitable Handler pass-through. The example
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich configuration below will pass all requests for PHP scripts to the
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich specified FastCGI server using reverse proxy.
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich This feature is available in Apache HTTP Server 2.4.10 and later. For performance
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich reasons, you will want to define a <a href="/mod_proxy.html#worker">worker</a>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich representing the same fcgi:// backend. The benefit of this form is that it
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich allows the normal mapping of URI to filename to occur in the server, and the
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich local filesystem result is passed to the backend. When FastCGI is
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich configured this way, the server can calculate the most accurate
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich<FilesMatch \.php$>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich # Note: The only part that varies is /path/to/app.sock
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich</FilesMatch>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich<FilesMatch ...>
f778a0725b6b62370f1ac3f683caf2a3930920d0Klaus Luettich SetHandler "proxy:fcgi://localhost:9000"
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich</FilesMatch>
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich<FilesMatch ...>
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich SetHandler "proxy:balancer://myappcluster/"
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich</FilesMatch>
a7f97f28aa8227408d4008e0b12a7bd925ef51feKlaus Luettich<section id="env"><title>Environment Variables</title>
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski <p>In addition to the configuration directives that control the
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder behaviour of <module>mod_proxy</module>, there are a number of
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder <dfn>environment variables</dfn> that control the FCGI protocol
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski provider:</p>
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski <dd>By default <module>mod_proxy_fcgi</module> will neither create
1b05bdb88b90d3c947351f262d7ae7d68f0a4a6fTill Mossakowski nor export the <var>PATH_INFO</var> environment variable. This allows
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski the backend FCGI server to correctly determine <var>SCRIPT_NAME</var>
21dae7237ac384abdb94a81e00b3f099873ec623Till Mossakowski and <var>Script-URI</var> and be compliant with RFC 3875 section 3.3.
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski If instead you need <module>mod_proxy_fcgi</module> to generate
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski a "best guess" for <var>PATH_INFO</var>, set this env-var.
503e836b34d3abed34520eb4a0a345b5e13f248dTill Mossakowski This is a workaround for a bug in some FCGI implementations.</dd>
e379124f467e5d0ef7d3c0ca238bff0521f70831Till Mossakowski</modulesynopsis>