From a79ec7c3bda66655e573805cc776cc79dae07736 Mon Sep 17 00:00:00 2001
From: Luca Toscano <elukey@apache.org>
Date: Sun, 1 Apr 2018 07:33:41 +0000
Subject: [PATCH] mod_proxy.xml: docs improvements

Tried to clarify the doubts raised in PR 61225
(related also to 60458) and also split a single note
into multiple ones to improve the reader's attention span
(reading through a long block of text may cause loss
of attention to important details, as it happened to me :)



git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.4.x@1828128 13f79535-47bb-0310-9956-ffa450edef68
---
 docs/manual/mod/mod_proxy.xml | 28 ++++++++++++++++++++++------
 1 file changed, 22 insertions(+), 6 deletions(-)

diff --git a/docs/manual/mod/mod_proxy.xml b/docs/manual/mod/mod_proxy.xml
index 44a5f66bf2..834274b04b 100644
--- a/docs/manual/mod/mod_proxy.xml
+++ b/docs/manual/mod/mod_proxy.xml
@@ -955,6 +955,19 @@ ProxyPass "/mirror/foo" "http://backend.example.com"
     <code>backend.example.com</code> <em>except</em> requests made to
     <code>/mirror/foo/i</code>.</p>
 
+    <p>Mixing ProxyPass settings in different contexts does not work:</p>
+    <highlight language="config">
+ProxyPass "/mirror/foo/i" "!"
+&lt;Location "/mirror/foo/"&gt;
+    ProxyPass "http://backend.example.com/"
+&lt;/Location&gt;
+    </highlight>
+    <p>In this case, a request to <code>/mirror/foo/i</code> will get proxied,
+       because the <directive>ProxyPass</directive> directive in the Location block will be evaluated
+       first. The fact that <directive>ProxyPass</directive> supports both server and directory contexts
+       does not mean that their scope and position in the configuration file will
+       guarantee any ordering or override.</p>
+
     <note type="warning"><title>Ordering ProxyPass Directives</title>
       <p>The configured <directive module="mod_proxy">ProxyPass</directive>
       and <directive module="mod_proxy">ProxyPassMatch</directive>
@@ -963,12 +976,15 @@ ProxyPass "/mirror/foo" "http://backend.example.com"
       <directive module="mod_proxy">ProxyPass</directive> rules starting with the
       longest URLs first. Otherwise, later rules for longer URLS will be hidden
       by any earlier rule which uses a leading substring of the URL. Note that
-      there is some relation with worker sharing. In contrast, only one
-      <directive module="mod_proxy">ProxyPass</directive> directive can be placed
-      in a <directive module="core">Location</directive> block, and the most
-      specific location will take precedence.</p>
-
-      <p>For the same reasons, exclusions must come <em>before</em> the
+      there is some relation with worker sharing.</p>
+    </note>
+    <note type="warning"><title>Ordering ProxyPass Directives in Locations</title>
+      <p>Only one <directive module="mod_proxy">ProxyPass</directive> directive
+      can be placed in a <directive module="core">Location</directive> block,
+      and the most specific location will take precedence.</p>
+    </note>
+    <note type="warning"><title>Exclusions and the no-proxy environment variable</title>
+      <p>Exclusions must come <em>before</em> the
       general <directive>ProxyPass</directive> directives. In 2.4.26 and later, the "no-proxy"
       environment variable is an alternative to exclusions, and is the only
       way to configure an exclusion of a <directive>ProxyPass</directive>
-- 
2.40.0