mirror of
https://github.com/apache/httpd.git
synced 2026-10-23 22:49:01 +03:00
f429387652
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1793934 13f79535-47bb-0310-9956-ffa450edef68
315 lines
13 KiB
XML
315 lines
13 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
|
|
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
|
|
<!-- $LastChangedRevision$ -->
|
|
|
|
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
(the "License"); you may not use this file except in compliance with
|
|
the License. You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
-->
|
|
|
|
<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>
|
|
<seealso><module>mod_authnz_fcgi</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> <module>mod_proxy_fcgi</module> disables connection reuse by
|
|
default, so after a request has been completed the connection will NOT be
|
|
held open by that httpd child process and won't be reused. If the
|
|
FastCGI application is able to handle concurrent connections
|
|
from httpd, you can opt-in to connection reuse as shown in the following
|
|
example:</p>
|
|
|
|
<example><title>Single application instance, connection reuse (2.4.11 and later)</title>
|
|
<highlight language="config">
|
|
ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=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. Connection pooling is enabled.</p>
|
|
<example><title>PHP-FPM</title>
|
|
<highlight language="config">
|
|
ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
|
|
</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">
|
|
# UDS does not currently support connection reuse
|
|
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/"
|
|
<Proxy "balancer://myappcluster/">
|
|
BalancerMember "fcgi://localhost:4000"
|
|
BalancerMember "fcgi://localhost:4001"
|
|
</Proxy>
|
|
</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#workers">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. When FastCGI is
|
|
configured this way, the server can calculate the most accurate
|
|
PATH_INFO.
|
|
</p>
|
|
<example><title>Proxy via Handler</title>
|
|
<highlight language="config">
|
|
<FilesMatch "\.php$">
|
|
# Note: The only part that varies is /path/to/app.sock
|
|
SetHandler "proxy:unix:/path/to/app.sock|fcgi://localhost/"
|
|
</FilesMatch>
|
|
|
|
# Define a matching worker.
|
|
# The part that is matched to the SetHandler is the part that
|
|
# follows the pipe. If you need to distinguish, "localhost; can
|
|
# be anything unique.
|
|
<Proxy "fcgi://localhost/" enablereuse=on max=10>
|
|
</Proxy>
|
|
|
|
<FilesMatch ...>
|
|
SetHandler "proxy:fcgi://localhost:9000"
|
|
</FilesMatch>
|
|
|
|
<FilesMatch ...>
|
|
SetHandler "proxy:balancer://myappcluster/"
|
|
</FilesMatch>
|
|
</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>When configured via <directive module="mod_proxy"
|
|
>ProxyPass</directive> or <directive module="mod_proxy"
|
|
>ProxyPassMatch</directive>, <module>mod_proxy_fcgi</module> will not
|
|
set 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. This
|
|
variable can be set to multiple values to tweak at how the best guess
|
|
is chosen (In 2.4.11 and later only):
|
|
<dl>
|
|
<dt>first-dot</dt>
|
|
<dd>PATH_INFO is split from the slash following the
|
|
<em>first</em> "." in the URL.</dd>
|
|
<dt>last-dot</dt>
|
|
<dd>PATH_INFO is split from the slash following the
|
|
<em>last</em> "." in the URL.</dd>
|
|
<dt>full</dt>
|
|
<dd>PATH_INFO is calculated by an attempt to map the URL to the
|
|
local filesystem.</dd>
|
|
<dt>unescape</dt>
|
|
<dd>PATH_INFO is the path component of the URL, unescaped /
|
|
decoded.</dd>
|
|
<dt>any other value</dt>
|
|
<dd>PATH_INFO is the same as the path component of the URL.
|
|
Originally, this was the only proxy-fcgi-pathinfo option.</dd>
|
|
</dl>
|
|
</dd>
|
|
</dl>
|
|
</section>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyFCGIBackendType</name>
|
|
<description>Specify the type of backend FastCGI application</description>
|
|
<syntax>ProxyFCGIBackendType FPM|GENERIC</syntax>
|
|
<default>ProxyFCGIBackendType FPM</default>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
<compatibility>Available in version 2.4.26 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>This directive allows the type of backend FastCGI application to be
|
|
specified. Some FastCGI servers, such as PHP-FPM, use historical quirks of
|
|
environment variables to identify the type of proxy server being used. Set
|
|
this directive to "GENERIC" if your non PHP-FPM application has trouble
|
|
interpreting environment variables such as SCRIPT_FILENAME or PATH_TRANSLATED
|
|
as set by the server.</p>
|
|
|
|
<p>One example of values that change based on the setting of this directive is
|
|
SCRIPT_FILENAME. When using <module>mod_proxy_fcgi</module> historically,
|
|
SCRIPT_FILENAME was prefixed with the string "proxy:fcgi://". This variable is
|
|
what some generic FastCGI applications would read as their script input, but
|
|
PHP-FPM would strip the prefix then remember it was talking to Apache. In
|
|
2.4.21 through 2.4.25, this prefix was automatically stripped by the server,
|
|
breaking the ability of PHP-FPM to detect and interoperate with Apache in some
|
|
scenarios.</p>
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
<directivesynopsis>
|
|
<name>ProxyFCGISetEnvIf</name>
|
|
<description>Allow variables sent to FastCGI servers to be fixed up</description>
|
|
<syntax>ProxyFCGISetEnvIf <var>conditional-expression</var>
|
|
[!]<var>environment-variable-name</var>
|
|
[<var>value-expression</var>]</syntax>
|
|
<contextlist><context>server config</context>
|
|
<context>virtual host</context><context>directory</context>
|
|
<context>.htaccess</context></contextlist>
|
|
<override>FileInfo</override>
|
|
<compatibility>Available in version 2.4.26 and later</compatibility>
|
|
|
|
<usage>
|
|
<p>Just before passing a request to the configured FastCGI server, the core of
|
|
the web server sets a number of environment variables based on details of the
|
|
current request. FastCGI programs often uses these environment variables
|
|
as inputs that determine what underlying scripts they will process, or what
|
|
output they directly produce.</p>
|
|
<p>Examples of noteworthy environment variables are:</p>
|
|
<ul>
|
|
<li>SCRIPT_NAME</li>
|
|
<li>SCRIPT_FILENAME</li>
|
|
<li>REQUEST_URI</li>
|
|
<li>PATH_INFO</li>
|
|
<li>PATH_TRANSLATED</li>
|
|
</ul>
|
|
|
|
<p>This directive allows the environment variables above, or any others of
|
|
interest, to be overridden. This directive is evaluated after the initial
|
|
values for these variables are set, so they can be used as input into both
|
|
the condition expressions and value expressions.</p>
|
|
<p>Parameter syntax:</p>
|
|
<dl>
|
|
<dt>conditional-expression</dt>
|
|
<dd>Specifies an expression that controls whether the environment variable that
|
|
follows will be modified. For information on the expression syntax, see
|
|
the examples that follow or the full specification at the
|
|
<a href="../expr.html">ap_expr</a> documentation.
|
|
</dd>
|
|
<dt>environment-variable-name</dt>
|
|
<dd> Specifies the CGI environment variable to change,
|
|
such as PATH_INFO. If preceded by an exclamation point, the variable
|
|
will be unset.</dd>
|
|
<dt>value-expression</dt>
|
|
<dd>Specifies the replacement value for the preceding environment variable.
|
|
Backreferences, such as "$1", can be included from regular expression
|
|
captures in <var>conditional-expression</var>. If omitted, the variable is
|
|
set (or overridden) to an empty string — but see the Note below.</dd>
|
|
</dl>
|
|
|
|
<example>
|
|
<highlight language="config">
|
|
# A basic, unconditional override
|
|
ProxyFCGISetEnvIf "true" PATH_INFO "/example"
|
|
|
|
# Use an environment variable in the value
|
|
ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
|
|
|
|
# Use captures in the conditions and backreferences in the replacement
|
|
ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m|(/.*prefix)(\d+)(.*)|" PATH_TRANSLATED "$1$3"
|
|
</highlight>
|
|
</example>
|
|
|
|
<note><title>Note: Unset vs. Empty</title>
|
|
The following will unset <code>VARIABLE</code>, preventing it from being sent
|
|
to the FastCGI server:
|
|
|
|
<highlight language="config">ProxyFCGISetEnvIf true !VARIABLE</highlight>
|
|
|
|
Whereas the following will erase any existing <em>value</em> of
|
|
<code>VARIABLE</code> (by setting it to the empty string), but the empty
|
|
<code>VARIABLE</code> will still be sent to the server:
|
|
|
|
<highlight language="config">ProxyFCGISetEnvIf true VARIABLE</highlight>
|
|
|
|
The CGI/1.1 specification
|
|
<a href="https://tools.ietf.org/html/rfc3875#section-4.1">does not
|
|
distinguish</a> between a variable with an empty value and a variable that
|
|
does not exist. However, many CGI and FastCGI implementations distinguish (or
|
|
allow scripts to distinguish) between the two. The choice of which to use is
|
|
dependent upon your implementation and your reason for modifying the variable.
|
|
</note>
|
|
|
|
</usage>
|
|
</directivesynopsis>
|
|
|
|
</modulesynopsis>
|