From: Rich Bowen Date: Thu, 30 Apr 2026 17:17:31 +0000 (+0000) Subject: rewrite guide: redistribute advanced.xml recipes to topical files (BZ 58892, step 1) X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=4b223dc3822f7badf441f55f31784e7e4cc6f940;p=thirdparty%2Fapache%2Fhttpd.git rewrite guide: redistribute advanced.xml recipes to topical files (BZ 58892, step 1) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933611 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/rewrite/avoid.xml b/docs/manual/rewrite/avoid.xml index 2dab02fefe..c8ae7e5d74 100644 --- a/docs/manual/rewrite/avoid.xml +++ b/docs/manual/rewrite/avoid.xml @@ -243,5 +243,60 @@ and in certain other directives.

+
+ + Load Balancing + +
+
Description:
+ +
+

We wish to distribute load across several back-end + servers.

+
+ +
Solution:
+ +
+

Use mod_proxy_balancer, 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 mod_rewrite approach.

+ + +<Proxy "balancer://mycluster"> + BalancerMember "http://one.example.com" + BalancerMember "http://two.example.com" + BalancerMember "http://three.example.com" +</Proxy> +ProxyPass "/" "balancer://mycluster/" +ProxyPassReverse "/" "balancer://mycluster/" + + +
+ +
Discussion:
+
+ +

It is possible to accomplish rudimentary random load balancing using +mod_rewrite with a rnd +RewriteMap:

+ + +RewriteEngine on +RewriteMap lb "rnd:/path/to/serverlist.txt" +RewriteRule "^/(.*)" "http://${lb:servers}/$1" [P,L] + + +

However, mod_proxy_balancer is far more flexible and +featureful than anything you can cobble together using +mod_rewrite, and is the recommended approach.

+ +
+
+ +
+ diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml index 09347d5a68..5b8da69ca2 100644 --- a/docs/manual/rewrite/flags.xml +++ b/docs/manual/rewrite/flags.xml @@ -347,6 +347,33 @@ CustomLog "logs/access_log" combined env=!image

Note that this same effect can be obtained using SetEnvIf. This technique is offered as an example, not as a recommendation.

+ +

Setting environment variables for tracking rewrites

+ +

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.

+ + +RewriteEngine on +RewriteRule "^/horse/(.*)" "/pony/$1" [E=rewritten:1] + + +

Later in your ruleset you might check for this environment +variable using a RewriteCond:

+ + +RewriteCond "%{ENV:rewritten}" =1 + + +

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_".

END diff --git a/docs/manual/rewrite/remapping.xml b/docs/manual/rewrite/remapping.xml index c1832ef65b..3038adec48 100644 --- a/docs/manual/rewrite/remapping.xml +++ b/docs/manual/rewrite/remapping.xml @@ -655,5 +655,155 @@ RewriteRule "^/?path/([^/]+)/([^/]+)" "/path?$1=$2" [PT]
+
+ + Structured Userdirs + +
+
Description:
+ +
+

Some sites with thousands of users use a + structured homedir layout, i.e. each homedir is in a + subdirectory which begins (for instance) with the first + character of the username. So, /~larry/anypath + is /home/l/larry/public_html/anypath + while /~waldo/anypath is + /home/w/waldo/public_html/anypath.

+
+ +
Solution:
+ +
+

We use the following ruleset to expand the tilde URLs + into the above layout.

+ + +RewriteEngine on +RewriteRule "^/~(([a-z])[a-z0-9]+)(.*)" "/home/$2/$1/public_html$3" + +
+
+ +
+ +
+ + Redirecting Anchors + +
+
Description:
+ +
+

By default, redirecting to an HTML anchor doesn't work, + because mod_rewrite escapes the # character, + turning it into %23. This, in turn, breaks the + redirection.

+
+ +
Solution:
+ +
+

Use the [NE] flag on the + RewriteRule. NE stands for No Escape. +

+
+ +
Discussion:
+
This technique will of course also work with other + special characters that mod_rewrite, by default, URL-encodes.
+
+ +
+ +
+ + Time-Dependent Rewriting + +
+
Description:
+ +
+

We wish to use mod_rewrite to serve different content based on + the time of day.

+
+ +
Solution:
+ +
+

There are a lot of variables named TIME_xxx + for rewrite conditions. In conjunction with the special + lexicographic comparison patterns <STRING, + >STRING and =STRING we can + do time-dependent redirects:

+ + +RewriteEngine on +RewriteCond "%{TIME_HOUR}%{TIME_MIN}" >0700 +RewriteCond "%{TIME_HOUR}%{TIME_MIN}" <1900 +RewriteRule "^foo\.html$" "foo.day.html" [L] +RewriteRule "^foo\.html$" "foo.night.html" + + +

This provides the content of foo.day.html + under the URL foo.html from + 07:01-18:59 and at the remaining time the + contents of foo.night.html.

+ + mod_cache, intermediate proxies + and browsers may each cache responses and cause the either page to be + shown outside of the time-window configured. + mod_expires may be used to control this + effect. You are, of course, much better off simply serving the + content dynamically, and customizing it based on the time of day. + +
+
+ +
+ +
+ + On-the-fly Content-Regeneration + +
+
Description:
+ +
+

We wish to dynamically generate content, but store it + statically once it is generated. This rule will check for the + existence of the static file, and if it's not there, generate + it. The static files can be removed periodically, if desired (say, + via cron) and will be regenerated on demand.

+
+ +
Solution:
+ +
+ This is done via the following ruleset: + + +# This example is valid in per-directory context only +RewriteCond "%{REQUEST_URI}" !-U +RewriteRule "^(.+)\.html$" "/regenerate_page.cgi" [PT,L] + + +

The -U operator determines whether the test string + (in this case, REQUEST_URI) is a valid URL. It does + this via a subrequest. In the event that this subrequest fails - + that is, the requested resource doesn't exist - this rule invokes + the CGI program /regenerate_page.cgi, which generates + the requested resource and saves it into the document directory, so + that the next time it is requested, a static copy can be served.

+ +

In this way, documents that are infrequently updated can be served in + static form. if documents need to be refreshed, they can be deleted + from the document directory, and they will then be regenerated the + next time they are requested.

+
+
+ +
+ diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml index ef16f845e6..81b7c6f808 100644 --- a/docs/manual/rewrite/rewritemap.xml +++ b/docs/manual/rewrite/rewritemap.xml @@ -470,6 +470,65 @@ RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s" (such as case-sensitivity) required for your database.

+ +
+ + URL-based sharding across multiple backends + +
+
Description:
+ +
+

A common technique for distributing the burden of + server load or storage space is called "sharding". + When using this method, a front-end server will use the + url to consistently "shard" users or objects to separate + backend servers.

+
+ +
Solution:
+ +
+

A mapping is maintained, from users to target servers, in + external map files. They look like:

+ + +user1 physical_host_of_user1
+user2 physical_host_of_user2
+# ... and so on + + +

We put this into a map.users-to-hosts file. The + aim is to map;

+ + +/u/user1/anypath + + +

to

+ + +http://physical_host_of_user1/u/user/anypath + + +

thus every URL path need not be valid on every backend physical + host. The following ruleset does this for us with the help of the map + files assuming that server0 is a default server which will be used if + a user has no entry in the map:

+ + +RewriteEngine on +RewriteMap users-to-hosts "txt:/path/to/map.users-to-hosts" +RewriteRule "^/u/([^/]+)/?(.*)" "http://${users-to-hosts:$1|server0}/u/$1/$2" + +
+
+ +

See the RewriteMap + documentation for more discussion of the syntax of this directive.

+ +
+
Summary