From: Yann Ylavic <ylavic@apache.org>
Date: Mon, 13 Dec 2021 16:42:05 +0000 (+0000)
Subject: Merge r1890477, r1895895, r1895907 from trunk: [skip ci]
X-Git-Tag: candidate-2.4.52-rc1~37
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=093c08c6c141e2c0a9be2cc45b5d5fd0821faf1d;p=thirdparty%2Fapache%2Fhttpd.git

Merge r1890477, r1895895, r1895907 from trunk: [skip ci]

Add mapping = servlet / encoded

Improve docs for ProxyPass mapping= parameter.

Add a note about aliging mapping= with the backend's.

Submitted by: jfclere, ylavic, ylavic


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1895908 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 64fe9caaa61..cc980a0b27a 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -1244,6 +1244,33 @@ ProxyPass "/example" "http://backend.example.com" max=20 ttl=120 retry=300
         <td><p>Protocol accepted in the Upgrade header by <module>mod_proxy_wstunnel</module>.
         See the documentation of this module for more details.</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 <module>mod_proxy</module>
+        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>&lt;Location&gt;</code>) will be matched using the
+        same mapping.
+        <p><code>mapping=encoded</code> prevents the %-decoding of the <var>uri-path</var> so
+        that one can match for instance <code>/some%2furi%2fpath%2fwith%2fslash</code> in a
+        <code>ProxyPass</code> or in a <code>&lt;Location&gt;</code> context.</p>
+        <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:</p>
+        <p><code>  &lt;Location /some/path&gt;</code> or:</p>
+        <p><code>  ProxyPass "/some/path" "https://tomcat.example.com/some/path"</code></p>
+        <p>regardless of the requested path parameters.</p>
+    <note><title>Note</title>
+        <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>&lt;Location&gt;</code> blocks for paths that are mapped by <module>mod_proxy</module>
+        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>
+    </note>
+    </td></tr>
 
     </table>