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