diff options
Diffstat (limited to 'docs/manual/mod/mod_proxy.html.en')
| -rw-r--r-- | docs/manual/mod/mod_proxy.html.en | 230 |
1 files changed, 175 insertions, 55 deletions
diff --git a/docs/manual/mod/mod_proxy.html.en b/docs/manual/mod/mod_proxy.html.en index bc950ce..211ec75 100644 --- a/docs/manual/mod/mod_proxy.html.en +++ b/docs/manual/mod/mod_proxy.html.en @@ -1,7 +1,7 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> +<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> -<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" /> +<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX This file is generated from xml source: DO NOT EDIT @@ -27,13 +27,13 @@ <div id="preamble"><h1>Apache Module mod_proxy</h1> <div class="toplang"> <p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> | -<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | +<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | <a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> </div> <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Multi-protocol proxy/gateway server</td></tr> <tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> -<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_module</td></tr> -<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy.c</td></tr></table> +<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>proxy_module</td></tr> +<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_proxy.c</td></tr></table> <h3>Summary</h3> <div class="warning"><h3>Warning</h3> @@ -73,7 +73,9 @@ <tr><td>ftp</td><td><code class="module"><a href="../mod/mod_proxy_ftp.html">mod_proxy_ftp</a></code></td></tr> <tr><td>HTTP/0.9, HTTP/1.0, and HTTP/1.1</td><td><code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code></td></tr> + <tr><td>HTTP/2.0</td><td><code class="module"><a href="../mod/mod_proxy_http2.html">mod_proxy_http2</a></code></td></tr> <tr><td>SCGI</td><td><code class="module"><a href="../mod/mod_proxy_scgi.html">mod_proxy_scgi</a></code></td></tr> + <tr><td>UWSGI</td><td><code class="module"><a href="../mod/mod_proxy_uwsgi.html">mod_proxy_uwsgi</a></code></td></tr> <tr><td>WS and WSS (Web-sockets)</td><td><code class="module"><a href="../mod/mod_proxy_wstunnel.html">mod_proxy_wstunnel</a></code></td></tr> </table> </li> @@ -107,6 +109,7 @@ <li><img alt="" src="../images/down.gif" /> <a href="#balancerpersist">BalancerPersist</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#noproxy">NoProxy</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#proxy"><Proxy></a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#proxy100continue">Proxy100Continue</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#proxyaddheaders">ProxyAddHeaders</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#proxybadheader">ProxyBadHeader</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#proxyblock">ProxyBlock</a></li> @@ -216,6 +219,8 @@ ProxyVia On Require host internal.example.com </Proxy></pre> </div> + <div class="example"><h3><a id="wsupgrade" name="wsupgrade">Websocket Upgrade (2.4.47 and later)</a></h3><pre class="prettyprint lang-config">ProxyPass "/some/ws/capable/path/" "http://example.com/some/ws/capable/path/" upgrade=websocket</pre> +</div> </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="handler" id="handler">Access via Handler</a></h2> @@ -460,9 +465,6 @@ ProxyPass "/examples" "http://backend.example.com/examples" timeout=10</pre> Content-Length header, but the server is configured to filter incoming request bodies.</p> - <p><code class="directive"><a href="../mod/core.html#limitrequestbody">LimitRequestBody</a></code> only applies to - request bodies that the server will spool to disk</p> - </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="x-headers" id="x-headers">Reverse Proxy Request Headers</a></h2> @@ -494,7 +496,7 @@ ProxyPass "/examples" "http://backend.example.com/examples" timeout=10</pre> other request headers.</p> <p>Note: If you need to specify custom request headers to be - added to the forwarded request, use the + added to the forwarded request, use the <code class="directive"><a href="../mod/mod_headers.html#requestheader">RequestHeader</a></code> directive.</p> @@ -738,13 +740,13 @@ NoProxy ".example.com" "192.168.112.0/21"</pre> <div class="note"><h3>Differences from the Location configuration section</h3> - <p>A backend URL matches the configuration section if it begins with the + <p>A backend URL matches the configuration section if it begins with the the <var>wildcard-url</var> string, even if the last path segment in the - directive only matches a prefix of the backend URL. For example, - <Proxy "http://example.com/foo"> matches all of - http://example.com/foo, http://example.com/foo/bar, and + directive only matches a prefix of the backend URL. For example, + <Proxy "http://example.com/foo"> matches all of + http://example.com/foo, http://example.com/foo/bar, and http://example.com/foobar. The matching of the final URL differs - from the behavior of the <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, which for purposes of this note + from the behavior of the <code class="directive"><a href="../mod/core.html#location"><Location></a></code> section, which for purposes of this note treats the final path component as if it ended in a slash.</p> <p>For more control over the matching, see <code class="directive"><ProxyMatch></code>.</p> </div> @@ -756,6 +758,27 @@ NoProxy ".example.com" "192.168.112.0/21"</pre> </ul> </div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="directive-section"><h2><a name="Proxy100Continue" id="Proxy100Continue">Proxy100Continue</a> <a name="proxy100continue" id="proxy100continue">Directive</a></h2> +<table class="directive"> +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Forward 100-continue expectation to the origin server</td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>Proxy100Continue Off|On</code></td></tr> +<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>Proxy100Continue On</code></td></tr> +<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in version 2.4.40 and later</td></tr> +</table> + <p>This directive determines whether the proxy should forward 100-continue + <em>Expect:</em>ation to the origin server and thus let it decide when/if + the HTTP request body should be read, or when <code>Off</code> the proxy + should generate <em>100 Continue</em> intermediate response by itself before + forwarding the request body.</p> + <div class="note"><h3>Effectiveness</h3> + <p>This option is of use only for HTTP proxying, as handled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p> + </div> + +</div> +<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="ProxyAddHeaders" id="ProxyAddHeaders">ProxyAddHeaders</a> <a name="proxyaddheaders" id="proxyaddheaders">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add proxy information in X-Forwarded-* headers</td></tr> @@ -865,11 +888,12 @@ ProxyDomain ".example.com"</pre> <div class="directive-section"><h2><a name="ProxyErrorOverride" id="ProxyErrorOverride">ProxyErrorOverride</a> <a name="proxyerroroverride" id="proxyerroroverride">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override error pages for proxied content</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride On|Off</code></td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyErrorOverride Off|On [<var>code</var> ...]</code></td></tr> <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyErrorOverride Off</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The list of status codes was added in 2.4.47</td></tr> </table> <p>This directive is useful for reverse-proxy setups where you want to have a common look and feel on the error pages seen by the end user. @@ -882,6 +906,20 @@ ProxyDomain ".example.com"</pre> <p>This directive does not affect the processing of informational (1xx), normal success (2xx), or redirect (3xx) responses.</p> + <p>By default <code class="directive">ProxyErrorOverride</code> affects all responses with codes between 400 (including) + and 600 (excluding).</p> + + <div class="example"><h3>Example for default behavior</h3><pre class="prettyprint lang-config">ProxyErrorOverride On</pre> +</div> + + <p>To change the default behavior, you can specify the status codes to consider, separated by spaces. + If you do so, all other status codes will be ignored. + You can only specify status codes, that are considered error codes: between 400 (including) + and 600 (excluding).</p> + + <div class="example"><h3>Example for custom status codes</h3><pre class="prettyprint lang-config">ProxyErrorOverride On 403 405 500 501 502 503 504</pre> +</div> + </div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="ProxyIOBufferSize" id="ProxyIOBufferSize">ProxyIOBufferSize</a> <a name="proxyiobuffersize" id="proxyiobuffersize">Directive</a></h2> @@ -946,7 +984,7 @@ proxied resources</td></tr> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="ProxyMaxForwards" id="ProxyMaxForwards">ProxyMaxForwards</a> <a name="proxymaxforwards" id="proxymaxforwards">Directive</a></h2> <table class="directive"> -<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximium number of proxies that a request can be forwarded +<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Maximum number of proxies that a request can be forwarded through</td></tr> <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyMaxForwards <var>number</var></code></td></tr> <tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ProxyMaxForwards -1</code></td></tr> @@ -1321,7 +1359,7 @@ ProxyPass "/mirror/foo" "http://backend.example.com"</pre> </td></tr> <tr><td>timeout</td> <td><code class="directive"><a href="#proxytimeout">ProxyTimeout</a></code></td> - <td>Connection timeout in seconds. + <td>Socket timeout in seconds. The number of seconds Apache httpd waits for data sent by / to the backend. </td></tr> <tr><td>ttl</td> @@ -1338,13 +1376,59 @@ ProxyPass "/mirror/foo" "http://backend.example.com"</pre> </td></tr> <tr><td>secret</td> <td>-</td> - <td><p>Value of secret used by <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>. - See the documentation of this module for more details.</p> + <td>Value of secret used by <code class="module"><a href="../mod/mod_proxy_ajp.html">mod_proxy_ajp</a></code>. + It must be identical to the secret configured on the server side of the + AJP connection.<br /> + Available in Apache HTTP Server 2.4.42 and later. </td></tr> - <tr><td>upgrade</td> - <td>WebSocket</td> - <td><p>Protocol accepted in the Upgrade header by <code class="module"><a href="../mod/mod_proxy_wstunnel.html">mod_proxy_wstunnel</a></code>. - See the documentation of this module for more details.</p> + <tr><td><a id="upgrade" name="upgrade">upgrade</a></td> + <td>-</td> + <td><p>Protocol accepted by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> or + <code class="module"><a href="../mod/mod_proxy_wstunnel.html">mod_proxy_wstunnel</a></code> for the HTTP Upgrade mechanism + upon negotiation by the HTTP client/browser (per + <a href="https://www.ietf.org/rfc/rfc9110.html#name-upgrade">RFC 9110 - Upgrade</a>). + See the <a href="#protoupgrade">Protocol Upgrade</a> note below</p> + </td></tr> + <tr><td>mapping</td> + <td>-</td> + <td><p>Type of mapping between the <var>path</var> and the <var>url</var>. + This determines the normalization and/or (non-)decoding that <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> + will apply to the requested <var>uri-path</var> before matching the <var>path</var>. If + a mapping matches, it's committed to the <var>uri-path</var> such that all the directory + contexts that use a path (like <code><Location></code>) will be matched using the + same mapping.</p> + <p><code>mapping=encoded</code> prevents the %-decoding of the <var>uri-path</var> so + that one can use for instance configurations like:</p> + <pre class="prettyprint lang-config">ProxyPass "/special%3Fsegment" "https://example.com/special%3Fsegment" mapping=encoded</pre> + + <pre class="prettyprint lang-config"><Location "/special%3Fsegment"> + Require ip 172.17.2.0/24 +</Location></pre> + + <p><code>mapping=servlet</code> refers to the normalization defined by the Servlet + specification, which is for instance applied by Apache Tomcat for servlet containers + (notably the path parameters are ignored for the mapping). An <var>uri-path</var> like + <code>/some;foo/path</code> is then mapped as <code>/some/path</code> hence matches any + of the below regardless of the requested path parameters:</p> + <pre class="prettyprint lang-config">ProxyPass "/some/path" "https://servlet.example.com/some/path" mapping=servlet</pre> + + <pre class="prettyprint lang-config"><Location "/some/path"> + Require valid-user +</Location></pre> + + <div class="note"><h3>Note</h3> + <p>It is recommended to use the same mapping on the Apache httpd side than the one + used on the backend side. For instance when configuring authorizations in + <code><Location></code> blocks for paths that are mapped by <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> + to some servlet containers (like applications running on Apache Tomcat), one should + use the <code>mapping=servlet</code> setting to prevent path parameters and alike from + interfering with the authorizations that are to be enforced in by the Apache httpd.</p> + </div> + </td></tr> + <tr><td><a id="addressttl" name="addressttl">addressttl</a></td> + <td>-1</td> + <td><p>TTL in seconds for how long DNS resolutions of the backend address are cached. + -1 means until restart of Apache httpd.</p> </td></tr> </table> @@ -1394,7 +1478,7 @@ ProxyPass "/mirror/foo" "http://backend.example.com"</pre> <tr><td>stickysessionsep</td> <td>"."</td> <td>Sets the separation symbol in the session cookie. Some backend application servers - do not use the '.' as the symbol. For example, the Oracle Weblogic server uses + do not use the '.' as the symbol. For example, the Oracle Weblogic server uses '!'. The correct symbol can be set using this option. The setting of 'Off' signifies that no symbol is used. </td></tr> @@ -1496,8 +1580,8 @@ ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofail But this may be incompatible with some backends, particularly those that make use of <var>PATH_INFO</var>. The optional <var>nocanon</var> keyword suppresses this and passes the URL path "raw" to the - backend. Note that this keyword may affect the security of your backend, - as it removes the normal limited protection against URL-based attacks + backend. Note that this keyword may affect the security of your backend, + as it removes the normal limited protection against URL-based attacks provided by the proxy.</p> <p>Normally, mod_proxy will include the query string when @@ -1505,7 +1589,7 @@ ProxyPass "/" "balancer://mycluster/" stickysession=JSESSIONID|jsessionid nofail The optional <var>noquery</var> keyword (available in httpd 2.4.1 and later) prevents this.</p> - <p>The optional <var>interpolate</var> keyword, in combination with + <p>The optional <code>interpolate</code> keyword, in combination with <code class="directive"><a href="#proxypassinterpolateenv">ProxyPassInterpolateEnv</a></code>, causes the ProxyPass to interpolate environment variables, using the syntax <var>${VARNAME}</var>. Note that many of the standard CGI-derived @@ -1531,6 +1615,26 @@ ProxyPassReverse "/mirror/foo/" "http://backend.example.com/" ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> + <div class="note"><h3><a id="protoupgrade" name="protoupgrade">Protocol Upgrade</a></h3> + <p>Since Apache HTTP Server 2.4.47, protocol Upgrade (tunneling) can be handled + end-to-end by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> using the <code class="directive">ProxyPass</code> + parameter <var><a href="#upgrade">upgrade</a></var>.</p> + <p>End-to-end means that the HTTP Upgrade request from the client/browser is first + forwarded by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> to the origin server and the connection + will be upgraded (and tunneled by <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>) only if the origin + server accepts/initiates the upgrade (HTTP response <code>101 Switching Protocols</code>). + If the origin server responds with anything else <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> + will continue forwarding (and enforcing) the HTTP protocol as usual for this + connection.</p> + <p>See <a href="#wsupgrade">Websocket Upgrade (2.4.47 and later)</a> for an example of + configuration using <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code>.</p> + <p>For Apache HTTP Server 2.4.46 and earlier (or if + <code class="directive"><a href="../mod/mod_proxy_wstunnel.html#proxywebsocketfallbacktoproxyhttp">ProxyWebsocketFallbackToProxyHttp</a></code> + from 2.4.48 and later disables <code class="module"><a href="../mod/mod_proxy_http.html">mod_proxy_http</a></code> handling), see the + documentation of <code class="module"><a href="../mod/mod_proxy_wstunnel.html">mod_proxy_wstunnel</a></code> for how to proxy the WebSocket + protocol.</p> + </div> + </div> <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="directive-section"><h2><a name="ProxyPassInherit" id="ProxyPassInherit">ProxyPassInherit</a> <a name="proxypassinherit" id="proxypassinherit">Directive</a></h2> @@ -1564,7 +1668,7 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_proxy</td></tr> <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in httpd 2.2.9 and later</td></tr> </table> - <p>This directive, together with the <var>interpolate</var> argument to + <p>This directive, together with the <code>interpolate</code> argument to <code class="directive">ProxyPass</code>, <code class="directive">ProxyPassReverse</code>, <code class="directive">ProxyPassReverseCookieDomain</code>, and <code class="directive">ProxyPassReverseCookiePath</code>, @@ -1577,7 +1681,7 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> <code class="directive">ProxyPassReverseCookiePath</code> directives and causes them to substitute the value of an environment variable <code>varname</code> for the string <code>${varname}</code> - in configuration directives if the <var>interpolate</var> option is set.</p> + in configuration directives if the <code>interpolate</code> option is set.</p> <p>The scheme/hostname/port portion of <code class="directive">ProxyPass</code> may contain variables, but only the ones available when the directive is parsed (for example, using <code class="directive"><a href="../mod/core.html#define">Define</a></code>). @@ -1600,6 +1704,9 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Since 2.4.47 the <var>key=value</var> Parameters are honored +when the <var>url</var> parameter contains backreference(s) (see note below). +</td></tr> </table> <p>This directive is equivalent to <code class="directive"><a href="#proxypass">ProxyPass</a></code> but makes use of regular expressions instead of simple prefix matching. The @@ -1607,7 +1714,7 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> matches, the server will substitute any parenthesized matches into the given string and use it as a new <var>url</var>.</p> - <div class="note"><strong>Note: </strong>This directive cannot be used within a + <div class="note"><strong>Note: </strong>This directive cannot be used within a <code><Directory></code> context.</div> <p>Suppose the local server has address <code>http://example.com/</code>; @@ -1619,18 +1726,7 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> <p>will cause a local request for <code>http://example.com/foo/bar.gif</code> to be internally converted into a proxy request to <code>http://backend.example.com/foo/bar.gif</code>.</p> - <div class="note"><h3>Note</h3> - <p>The URL argument must be parsable as a URL <em>before</em> regexp - substitutions (as well as after). This limits the matches you can use. - For instance, if we had used</p> - <pre class="prettyprint lang-config">ProxyPassMatch "^(/.*\.gif)$" "http://backend.example.com:8000$1"</pre> - <p>in our previous example, it would fail with a syntax error - at server startup. This is a bug (PR 46665 in the ASF bugzilla), - and the workaround is to reformulate the match:</p> - <pre class="prettyprint lang-config">ProxyPassMatch "^/(.*\.gif)$" "http://backend.example.com:8000/$1"</pre> - - </div> <p>The <code>!</code> directive is useful in situations where you don't want to reverse-proxy a subdirectory.</p> @@ -1647,6 +1743,20 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> expression, the original URL will be appended to the URL parameter. </p> </div> + <div class="note"> + <h3><code>key=value</code> Parameters versus <var>url</var> with backreference(s)</h3> + <p>Since Apache HTTP Server 2.4.47, the <code>key=value</code> Parameters + are no longer ignored in a <code class="directive">ProxyPassMatch</code> using + an <var>url</var> with backreference(s). However to keep the existing + behavior regarding reuse/keepalive of backend connections (which were + never reused before for these URLs), the parameter <var>enablereuse</var> + (or <var>disablereuse</var>) default to <code>off</code> (resp. <code>on</code>) + in this case. Setting <code>enablereuse=on</code> explicitely allows to + reuse connections <strong>unless</strong> some backreference(s) belong in + the <code>authority</code> part (hostname and/or port) of the <var>url</var> + (this condition is enforced since Apache HTTP Server 2.4.55, and produces + a warning at startup because these URLs are not reusable per se).</p> + </div> <div class="warning"> <h3>Security Warning</h3> @@ -1664,7 +1774,7 @@ ProxyPassReverse "/mirror/foo/" "https://backend.example.com/"</pre> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the URL in HTTP response headers sent from a reverse proxied server</td></tr> <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverse [<var>path</var>] <var>url</var> -[<var>interpolate</var>]</code></td></tr> +[interpolate]</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> @@ -1701,7 +1811,7 @@ ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre> <p>will not only cause a local request for the <code>http://example.com/mirror/foo/bar</code> to be internally converted into a proxy request to <code>http://backend.example.com/bar</code> - (the functionality which <code>ProxyPass</code> provides here). + (the functionality which <code>ProxyPass</code> provides here). It also takes care of redirects which the server <code>backend.example.com</code> sends when redirecting <code>http://backend.example.com/bar</code> to <code>http://backend.example.com/quux</code> . Apache httpd adjusts this to @@ -1714,8 +1824,8 @@ ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre> (<code>RewriteRule ... [P]</code>) from <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> because it doesn't depend on a corresponding <code class="directive"><a href="#proxypass">ProxyPass</a></code> directive.</p> - <p>The optional <var>interpolate</var> keyword, used together with - <code class="directive">ProxyPassInterpolateEnv</code>, enables interpolation + <p>The optional <code>interpolate</code> keyword, used together with + <code class="directive"><a href="#proxypassinterpolateenv">ProxyPassInterpolateEnv</a></code>, enables interpolation of environment variables specified using the format <var>${VARNAME}</var>. Note that interpolation is not supported within the scheme portion of a URL.</p> @@ -1735,7 +1845,7 @@ ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Domain string in Set-Cookie headers from a reverse- proxied server</td></tr> <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookieDomain <var>internal-domain</var> -<var>public-domain</var> [<var>interpolate</var>]</code></td></tr> +<var>public-domain</var> [interpolate]</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> @@ -1752,7 +1862,7 @@ string in <code>Set-Cookie</code> headers.</p> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Adjusts the Path string in Set-Cookie headers from a reverse- proxied server</td></tr> <tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyPassReverseCookiePath <var>internal-path</var> -<var>public-path</var> [<var>interpolate</var>]</code></td></tr> +<var>public-path</var> [interpolate]</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</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</td></tr> @@ -1766,7 +1876,7 @@ reverse proxy. This directive rewrites the <code>path</code> string in <var>internal-path</var>, the cookie path will be replaced with <var>public-path</var>. </p><p> -In the example given with +In the example given with <code class="directive"><a href="#proxypassreverse">ProxyPassReverse</a></code>, the directive: </p> <pre class="prettyprint lang-config">ProxyPassReverseCookiePath "/" "/mirror/foo/"</pre> @@ -1790,7 +1900,7 @@ request</td></tr> <tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Usable in directory context in 2.3.3 and later.</td></tr> </table> - <p>When enabled, this option will pass the Host: line from the incoming + <p>When enabled, this option will pass the <code>Host:</code> line from the incoming request to the proxied host, instead of the hostname specified in the <code class="directive"><a href="#proxypass">ProxyPass</a></code> line.</p> @@ -1825,10 +1935,11 @@ connections</td></tr> <div class="directive-section"><h2><a name="ProxyRemote" id="ProxyRemote">ProxyRemote</a> <a name="proxyremote" id="proxyremote">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle certain requests</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var></code></td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemote <var>match</var> <var>remote-server</var> [<var>username:password</var>]</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is usable only in httpd 2.4.59 and later.</td></tr> </table> <p>This defines remote proxies to this proxy. <var>match</var> is either the name of a URL-scheme that the remote server supports, or a partial URL @@ -1859,16 +1970,25 @@ ProxyRemote "ftp" "http://ftpproxy.mydomain:8080"</pre> webserver can be embedded within a virtualhost URL space even if that server is hidden by another forward proxy.</p> + <p>An optional third argument <var>username:password</var> may be + given, which defines the Basic authentication credentials to pass + to the configured remote proxy. The credentials will always be + sent without first waiting for the remote proxy to send a Basic + authentication challenge. The <a href="mod_proxy_http.html#env">Proxy-Chain-Auth</a> environment + variable has no effect if this argument is used.</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="ProxyRemoteMatch" id="ProxyRemoteMatch">ProxyRemoteMatch</a> <a name="proxyremotematch" id="proxyremotematch">Directive</a></h2> <table class="directive"> <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Remote proxy used to handle requests matched by regular expressions</td></tr> -<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var></code></td></tr> +<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ProxyRemoteMatch <var>regex</var> <var>remote-server</var> [<var>username:password</var>]</code></td></tr> <tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</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</td></tr> +<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The optional third argument is usable only in httpd 2.4.59 and later.</td></tr> </table> <p>The <code class="directive">ProxyRemoteMatch</code> is identical to the <code class="directive"><a href="#proxyremote">ProxyRemote</a></code> directive, except that @@ -2002,7 +2122,7 @@ expressions</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</td></tr> </table> - <p>This directive allows a user to specifiy a timeout on proxy requests. + <p>This directive allows a user to specify a timeout on proxy requests. This is useful when you have a slow/buggy appserver which hangs, and you would rather just return a timeout and fail gracefully instead of waiting however long it takes the server to return.</p> @@ -2045,9 +2165,9 @@ header for proxied requests</td></tr> </div> <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/mod/mod_proxy.html" title="English"> en </a> | -<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | +<a href="../fr/mod/mod_proxy.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | <a href="../ja/mod/mod_proxy.html" hreflang="ja" rel="alternate" title="Japanese"> ja </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> +</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 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 Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div> <script type="text/javascript"><!--//--><![CDATA[//><!-- var comments_shortname = 'httpd'; var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_proxy.html'; @@ -2065,7 +2185,7 @@ var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_proxy.html'; } })(window, document); //--><!]]></script></div><div id="footer"> -<p class="apache">Copyright 2019 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 2024 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/directives.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(); |