<div id="page-content">
<div id="preamble"><h1>Apache Module mod_proxy_fcgi</h1>
<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_fcgi.html" title="English"> en </a></p>
+<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_fcgi.html" title="English"> en </a> |
+<a href="../fr/mod/mod_proxy_fcgi.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>FastCGI support module for
<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></td></tr>
<li><img alt="" src="../images/down.gif" /> <a href="#examples">Examples</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#env">Environment Variables</a></li>
</ul><h3 class="directives">Directives</h3>
-<p>This module provides no
- directives.</p>
-<h3>See also</h3>
+<ul id="toc">
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyfcgibackendtype">ProxyFCGIBackendType</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#proxyfcgisetenvif">ProxyFCGISetEnvIf</a></li>
+</ul>
+<h3>Bugfix checklist</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">httpd changelog</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&list_id=144532&product=Apache%20httpd-2&query_format=specific&order=changeddate%20DESC%2Cpriority%2Cbug_severity&component=mod_proxy_fcgi">Known issues</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&component=mod_proxy_fcgi">Report a bug</a></li></ul><h3>See also</h3>
<ul class="seealso">
<li><code class="program"><a href="../programs/fcgistarter.html">fcgistarter</a></code></li>
<li><code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></li>
<li><code class="module"><a href="../mod/mod_authnz_fcgi.html">mod_authnz_fcgi</a></code></li>
-</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
+<li><a href="#comments_section">Comments</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="examples" id="examples">Examples</a></h2>
from httpd, you can opt-in to connection reuse as shown in the following
example:</p>
- <div class="example"><h3>Single application instance, connection reuse</h3><pre class="prettyprint lang-config">ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on</pre>
+ <div class="example"><h3>Single application instance, connection reuse (2.4.11 and later)</h3><pre class="prettyprint lang-config">ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on</pre>
</div>
<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>
- <div class="example"><h3>PHP-FPM with UDS</h3><pre class="prettyprint lang-config"> # UDS does not currently support connection reuse
- ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"</pre>
+ <div class="example"><h3>PHP-FPM with UDS</h3><pre class="prettyprint lang-config"># UDS does not currently support connection reuse
+ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"</pre>
</div>
<p>The balanced gateway needs <code class="module"><a href="../mod/mod_proxy_balancer.html">mod_proxy_balancer</a></code> and
default, and will be used for this example configuration.</p>
<div class="example"><h3>Balanced gateway to multiple application instances</h3><pre class="prettyprint lang-config">ProxyPass "/myapp/" "balancer://myappcluster/"
-<Proxy balancer://myappcluster/>
- BalancerMember fcgi://localhost:4000
- BalancerMember fcgi://localhost:4001
+<Proxy "balancer://myappcluster/">
+ BalancerMember "fcgi://localhost:4000"
+ BalancerMember "fcgi://localhost:4001"
</Proxy></pre>
</div>
# 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>
+
+# 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"
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:
+ is chosen (In 2.4.11 and later only):
<dl>
<dt>first-dot</dt>
<dd>PATH_INFO is split from the slash following the
</dl>
</dd>
</dl>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyFCGIBackendType" id="ProxyFCGIBackendType">ProxyFCGIBackendType</a> <a name="proxyfcgibackendtype" id="proxyfcgibackendtype">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Specify the type of backend FastCGI application</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFCGIBackendType FPM|GENERIC</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyFCGIBackendType FPM</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_fcgi</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.26 and later</td></tr>
+</table>
+<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 <code class="module"><a href="../mod/mod_proxy_fcgi.html">mod_proxy_fcgi</a></code> 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>
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="ProxyFCGISetEnvIf" id="ProxyFCGISetEnvIf">ProxyFCGISetEnvIf</a> <a name="proxyfcgisetenvif" id="proxyfcgisetenvif">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allow variables sent to FastCGI servers to be fixed up</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyFCGISetEnvIf <var>conditional-expression</var>
+ [!]<var>environment-variable-name</var>
+ [<var>value-expression</var>]</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
+<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy_fcgi</td></tr>
+<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.26 and later</td></tr>
+</table>
+<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>
+
+<div class="example"><pre class="prettyprint lang-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"</pre>
+</div>
+
+<div class="note"><h3>Note: Unset vs. Empty</h3>
+ The following will unset <code>VARIABLE</code>, preventing it from being sent
+ to the FastCGI server:
+
+ <pre class="prettyprint lang-config">ProxyFCGISetEnvIf true !VARIABLE</pre>
+
+
+ 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:
+
+ <pre class="prettyprint lang-config">ProxyFCGISetEnvIf true VARIABLE</pre>
+
+
+ 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.
+</div>
+
+
</div>
</div>
<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_fcgi.html" title="English"> en </a></p>
+<p><span>Available Languages: </span><a href="../en/mod/mod_proxy_fcgi.html" title="English"> en </a> |
+<a href="../fr/mod/mod_proxy_fcgi.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
<script type="text/javascript"><!--//--><![CDATA[//><!--
var comments_shortname = 'httpd';
}
})(window, document);
//--><!]]></script></div><div id="footer">
-<p class="apache">Copyright 2016 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
+<p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
if (typeof(prettyPrint) !== 'undefined') {
prettyPrint();