rewrite guide: redistribute advanced.xml recipes to topical files (BZ 58892, step 1)

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

Author: rbowen

docs/manual/rewrite/avoid.xml

@@ -243,5 +243,60 @@ and in certain other directives.</p>
 
 </section>
 
+<section id="load-balancing">
+
+  <title>Load Balancing</title>
+
+  <dl>
+    <dt>Description:</dt>
+
+    <dd>
+      <p>We wish to distribute load across several back-end
+      servers.</p>
+    </dd>
+
+    <dt>Solution:</dt>
+
+    <dd>
+      <p>Use <module>mod_proxy_balancer</module>, which provides a
+      flexible and featureful load-balancing solution. It supports
+      several balancing algorithms, session stickiness, health checks,
+      and dynamic configuration via the Balancer Manager — none of which
+      are possible with a <module>mod_rewrite</module> approach.</p>
+
+<highlight language="config">
+&lt;Proxy "balancer://mycluster"&gt;
+    BalancerMember "http://one.example.com"
+    BalancerMember "http://two.example.com"
+    BalancerMember "http://three.example.com"
+&lt;/Proxy&gt;
+ProxyPass        "/"  "balancer://mycluster/"
+ProxyPassReverse "/"  "balancer://mycluster/"
+</highlight>
+
+    </dd>
+
+    <dt>Discussion:</dt>
+    <dd>
+
+<p>It is possible to accomplish rudimentary random load balancing using
+<module>mod_rewrite</module> with a <code>rnd</code>
+<directive module="mod_rewrite">RewriteMap</directive>:</p>
+
+<highlight language="config">
+RewriteEngine on
+RewriteMap  lb       "rnd:/path/to/serverlist.txt"
+RewriteRule "^/(.*)" "http://${lb:servers}/$1"     [P,L]
+</highlight>
+
+<p>However, <module>mod_proxy_balancer</module> is far more flexible and
+featureful than anything you can cobble together using
+<module>mod_rewrite</module>, and is the recommended approach.</p>
+
+    </dd>
+  </dl>
+
+</section>
+
 </manualpage>
 

docs/manual/rewrite/flags.xml

@@ -153,7 +153,7 @@ characters rejected when they are copied into the query string unencoded.
 RewriteRule "^search/(.*)$" "/search.php/$1" "[BCTLS]"
 </highlight>
 
-<p>This flag is available in version 2.4.57 and later.</p>
+<p>This flag is available in version 2.5.1 and later.</p>
 
 </section>
 
@@ -168,7 +168,7 @@ escaped.
 RewriteRule "^search/(.*)$" "/search.php?term=$1" "[B,BNE=/]"
 </highlight>
 
-<p>This flag is available in version 2.4.57 and later.</p>
+<p>This flag is available in version 2.5.1 and later.</p>
 </section>
 
 <section id="flag_c"><title>C|chain</title>
@@ -223,6 +223,7 @@ security model.</dd>
 <dd>A value of 0 indicates that the cookie will persist only for the
 current browser session. This is the default value if none is
 specified.</dd>
+<dd>A negative value causes the cookie to be unset in the browser.</dd>
 
 <dt>Path</dt>
 <dd>The path, on the current website, for which the cookie is valid,
@@ -244,7 +245,7 @@ browsers that support this feature.</dd>
 <dt>samesite</dt>
 <dd>If set to anything other than <code>false</code> or <code>0</code>, the <code>SameSite</code>
 attribute is set to the specified value.  Typical values are <code>None</code>,
-<code>Lax</code>, and <code>Strict</code>. Available in 2.4.47 and later.</dd>
+<code>Lax</code>, and <code>Strict</code>. Available in 2.5.1 and later.</dd>
 </dl>
 
 
@@ -346,6 +347,33 @@ CustomLog   "logs/access_log"    combined env=!image
 <p>Note that this same effect can be obtained using <directive
 module="mod_setenvif">SetEnvIf</directive>. This technique is offered as
 an example, not as a recommendation.</p>
+
+<p><strong>Setting environment variables for tracking rewrites</strong></p>
+
+<p>At times, we want to maintain some kind of status when we
+perform a rewrite. For example, you want to make a note that
+you've done that rewrite, so that you can check later to see if a
+request came via that rewrite. One way to do this is by setting an
+environment variable.</p>
+
+<highlight language="config">
+RewriteEngine on
+RewriteRule   "^/horse/(.*)"   "/pony/$1" [E=<strong>rewritten:1</strong>]
+</highlight>
+
+<p>Later in your ruleset you might check for this environment
+variable using a RewriteCond:</p>
+
+<highlight language="config">
+RewriteCond "%{ENV:rewritten}"  =1
+</highlight>
+
+<p>Note that environment variables do not survive an external
+redirect. You might consider using the [CO] flag to set a
+cookie. For per-directory and htaccess rewrites, where the final
+substitution is processed as an internal redirect, environment
+variables from the previous round of rewriting are prefixed with
+"REDIRECT_". </p>
 </section>
 
 <section id="flag_end"><title>END</title>
@@ -495,7 +523,7 @@ pattern still matches (i.e., while the URI still contains an
 <code>A</code>), perform this substitution (i.e., replace the
 <code>A</code> with a <code>B</code>).</p>
 
-<p>In 2.4.8 and later, this module returns an error after 10,000 iterations to
+<p>In 2.5.0 and later, this module returns an error after 10,000 iterations to
 protect against unintended looping.  An alternative maximum number of
 iterations can be specified by adding to the N flag.  </p>
 <highlight language="config">
@@ -885,14 +913,14 @@ The <code>L</code> flag can be useful in this context to end the
     This protects from a malicious URL causing the expanded substitution to
     map to an unexpected filesystem location.</p>
 
-    <p><since>2.4.60</since></p>
+    <p><since>2.5.1</since></p>
 </section>
 <section id="flag_unc"><title>UNC</title>
     <p> Setting this flag prevents the merging of multiple leading slashes,
     as used in Windows UNC paths.  The flag is not necessary when the rules
     substitution starts with multiple literal slashes.</p>
 
-    <p><since>2.4.62</since></p>
+    <p><since>2.5.1</since></p>
 </section>
 
 </manualpage>