From: Rich Bowen Date: Thu, 30 Apr 2026 18:19:38 +0000 (+0000) Subject: rewrite guide: replace advanced.xml with deprecation stub (BZ 58892, step 2) X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=b10a91dc0341976fa6565ae7991f25b0e721b7ec;p=thirdparty%2Fapache%2Fhttpd.git rewrite guide: replace advanced.xml with deprecation stub (BZ 58892, step 2) git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933613 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/rewrite/advanced.xml b/docs/manual/rewrite/advanced.xml index 87f8710c5a..9895a1d8fd 100644 --- a/docs/manual/rewrite/advanced.xml +++ b/docs/manual/rewrite/advanced.xml @@ -27,332 +27,28 @@ -

This document supplements the mod_rewrite -reference documentation. It provides -a few advanced techniques using mod_rewrite.

- - - -Note that many of these examples won't work unchanged in your -particular server configuration, so it's important that you understand -them, rather than merely cutting and pasting the examples into your -configuration. +This document has been deprecated. Its content has +been reorganized into the following topical documents, where it can be +found alongside related recipes and examples. This page will be removed +in a future version of this documentation. + + -Module documentation -mod_rewrite introduction -Redirection and remapping -Controlling access -Virtual hosts -Proxying -Using RewriteMap - -When not to use mod_rewrite - -
- - 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 and the RewriteMap HowTo - for more discussion of the syntax of this directive.

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

-
-
- -
- -
- - Load Balancing - -
-
Description:
- -
-

We wish to randomly distribute load across several servers - using mod_rewrite.

-
- -
Solution:
- -
-

We'll use RewriteMap and a list of servers - to accomplish this.

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

serverlist.txt will contain a list of the servers:

- - -## serverlist.txt
-
-servers one.example.com|two.example.com|three.example.com
- - -

If you want one particular server to get more of the load than the -others, add it more times to the list.

- -
- -
Discussion
-
-

Apache comes with a load-balancing module - -mod_proxy_balancer - which is far more flexible and -featureful than anything you can cobble together using mod_rewrite.

-
-
- -
- -
- - 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. - -
-
- -
- -
- - Set Environment Variables Based On URL Parts - -
-
Description:
- -
-

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.

-
- -
Solution:
- -
-

Use the [E] flag to set 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_".

- -
-
- -