| <?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/reuse 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"> |
| 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> |
| <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> |
| <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> |