Return-Path: Delivered-To: apmail-httpd-cvs-archive@www.apache.org Received: (qmail 52304 invoked from network); 18 Mar 2011 13:37:52 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 18 Mar 2011 13:37:52 -0000 Received: (qmail 5600 invoked by uid 500); 18 Mar 2011 13:37:51 -0000 Delivered-To: apmail-httpd-cvs-archive@httpd.apache.org Received: (qmail 5523 invoked by uid 500); 18 Mar 2011 13:37:51 -0000 Mailing-List: contact cvs-help@httpd.apache.org; run by ezmlm Precedence: bulk Reply-To: dev@httpd.apache.org list-help: list-unsubscribe: List-Post: List-Id: Delivered-To: mailing list cvs@httpd.apache.org Received: (qmail 5513 invoked by uid 99); 18 Mar 2011 13:37:51 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 Mar 2011 13:37:51 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=5.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 18 Mar 2011 13:37:45 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 4C91123888CD; Fri, 18 Mar 2011 13:37:23 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1082915 [1/7] - /httpd/httpd/branches/2.2.x/docs/manual/rewrite/ Date: Fri, 18 Mar 2011 13:37:22 -0000 To: cvs@httpd.apache.org From: rbowen@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20110318133723.4C91123888CD@eris.apache.org> Author: rbowen Date: Fri Mar 18 13:37:20 2011 New Revision: 1082915 URL: http://svn.apache.org/viewvc?rev=1082915&view=rev Log: Brings the 2.2 rewrite docs up to the same level as the trunk rewrite docs. Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.html.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.xml.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/flags.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/htaccess.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/htaccess.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/htaccess.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/htaccess.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.html.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.xml.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.html.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.xml.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/intro.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/proxy.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/proxy.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/proxy.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/proxy.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/remapping.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/remapping.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/remapping.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/remapping.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewritemap.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.html.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.fr httpd/httpd/branches/2.2.x/docs/manual/rewrite/tech.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/vhosts.xml.meta Removed: httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_flags.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_flags.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_flags.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_flags.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide_advanced.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide_advanced.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide_advanced.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_guide_advanced.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_intro.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_intro.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_intro.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_intro.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_tech.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_tech.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_tech.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/rewrite_tech.xml.meta Modified: httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.html httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.html.en httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.html.tr.utf8 httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.html.zh-cn httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.xml httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.xml.meta httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.xml.tr httpd/httpd/branches/2.2.x/docs/manual/rewrite/index.xml.zh-cn Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html Fri Mar 18 13:37:20 2011 @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: access.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html.en URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html.en?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html.en (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.html.en Fri Mar 18 13:37:20 2011 @@ -0,0 +1,303 @@ + + + +Using mod_rewrite to control access - Apache HTTP Server + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.2

+
+
<-
+

Using mod_rewrite to control access

+
+

Available Languages:  en 

+
+ + +

This document supplements the mod_rewrite +reference documentation. It describes +how you can use mod_rewrite to control access to +various resources, and other related techniques. +This includes many examples of common uses of mod_rewrite, +including detailed descriptions of how each works.

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

Forbidding Image "Hotlinking"

+ + + +
+
Description:
+ +
+

The following technique forbids the practice of other sites + including your images inline in their pages. This practice is + often referred to as "hotlinking", and results in + your bandwidth being used to serve content for someone else's + site.

+
+ +
Solution:
+ +
+

This technique relies on the value of the + HTTP_REFERER variable, which is optional. As + such, it's possible for some people to circumvent this + limitation. However, most users will experience the failed + request, which should, over time, result in the image being + removed from that other site.

+

There are several ways that you can handle this + situation.

+ +

In this first example, we simply deny the request, if it didn't + initiate from a page on our site. For the purpose of this example, + we assume that our site is www.example.com.

+ +

+RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ - [F,NC] +

+ +

In this second example, instead of failing the request, we display + an alternate image instead.

+ +

+RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ /images/go-away.png [R,NC] +

+ +

In the third example, we redirect the request to an image on some + other site.

+ +

+RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ http://other.example.com/image.gif [R,NC] +

+ +

Of these techniques, the last two tend to be the most effective + in getting people to stop hotlinking your images, because they will + simply not see the image that they expected to see.

+ +
+ +
Discussion:
+ +
+

If all you wish to do is deny access to the resource, rather + than redirecting that request elsewhere, this can be + accomplished without the use of mod_rewrite:

+ +

+ SetEnvIf Referer example\.com localreferer
+ <FilesMatch \.(jpg|png|gif)$>
+ Order deny,allow
+ Deny from all
+ Allow from env=localreferer
+ </FilesMatch> +

+
+
+ +
top
+
+

Blocking of Robots

+ + + +
+
Description:
+ +
+

+ In this recipe, we discuss how to block persistent requests from + a particular robot, or user agent.

+ +

The standard for robot exclusion defines a file, + /robots.txt that specifies those portions of your + website where you which to exclude robots. However, some robots + do not honor these files. +

+ +

Note that there are methods of accomplishing this which do + not use mod_rewrite. Note also that any technique that relies on + the clients USER_AGENT string can be circumvented + very easily, since that string can be changed.

+
+ +
Solution:
+ +
+

We use a ruleset that specifies the directory to be + protected, and the client USER_AGENT that + identifies the malicious or persistent robot.

+ +

In this example, we are blocking a robot called + NameOfBadRobot from a location + /secret/files. You may also specify an IP address + range, if you are trying to block that user agent only from the + particular source.

+ +

+RewriteCond %{HTTP_USER_AGENT} ^NameOfBadRobot
+RewriteCond %{REMOTE_ADDR} =123\.45\.67\.[8-9]
+RewriteRule ^/secret/files/ - [F] +

+
+ +
Discussion:
+ +
+

+ Rather than using mod_rewrite for this, you can accomplish the + same end using alternate means, as illustrated here: +

+

+ SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway
+ <Location /secret/files>
+ Order allow,deny
+ Allow from all
+ Deny from env=goaway
+ </Location> +

+

+ As noted above, this technique is trivial to circumvent, by simply + modifying the USER_AGENT request header. If you + are experiencing a sustained attack, you should consider blocking + it at a higher level, such as at your firewall. +

+ +
+ +
+ +
top
+
+

Denying Hosts in a Blacklist

+ + + +
+
Description:
+ +
+

We wish to maintain a blacklist of hosts, rather like + hosts.deny, and have those hosts blocked from + accessing our server.

+
+ +
Solution:
+ +
+

+RewriteEngine on
+RewriteMap hosts-deny txt:/path/to/hosts.deny
+RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]
+RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND
+RewriteRule ^ - [F] +

+ +

+##
+## hosts.deny
+##
+## ATTENTION! This is a map, not a list, even when we treat it as such.
+## mod_rewrite parses it for key/value pairs, so at least a
+## dummy value "-" must be present for each entry.
+##
+
+193.102.180.41 -
+bsdti1.sdm.de -
+192.76.162.40 -
+

+
+ +
Discussion:
+
+

+ The second RewriteCond assumes that you have HostNameLookups turned + on, so that client IP addresses will be resolved. If that's not the + case, you should drop the second RewriteCond, and drop the + [OR] flag from the first RewriteCond. +

+
+
+ +
top
+
+

Referer-based Deflector

+ + + +
+
Description:
+ +
+

Redirect requests based on the Referer from which the request + came, with different targets per Referer.

+
+ +
Solution:
+ +
+

The following ruleset uses a map file to associate each Referer + with a redirection target.

+ +

+RewriteMap deflector txt:/path/to/deflector.map
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}} =-
+RewriteRule ^ %{HTTP_REFERER} [R,L]
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
+RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L] +

+ +

The map file lists redirection targets for each referer, or, if + we just wish to redirect back to where they came from, a "-" is + placed in the map:

+ +

+##
+## deflector.map
+##
+
+http://badguys.example.com/bad/index.html -
+http://badguys.example.com/bad/index2.html -
+http://badguys.example.com/bad/index3.html http://somewhere.example.com/ +

+ +
+
+ +
+
+

Available Languages:  en 

+
+ \ No newline at end of file Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml Fri Mar 18 13:37:20 2011 @@ -0,0 +1,307 @@ + + + + + + + + + Rewrite + +Using mod_rewrite to control access + + + +

This document supplements the mod_rewrite +reference documentation. It describes +how you can use mod_rewrite to control access to +various resources, and other related techniques. +This includes many examples of common uses of mod_rewrite, +including detailed descriptions of how each works.

+ +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. + + +Module documentation +mod_rewrite introduction +Redirection and remapping + +Virtual hosts +Proxying +Using RewriteMap +Advanced techniques and tricks +When not to use mod_rewrite + +
+ + Forbidding Image "Hotlinking" + +
+
Description:
+ +
+

The following technique forbids the practice of other sites + including your images inline in their pages. This practice is + often referred to as "hotlinking", and results in + your bandwidth being used to serve content for someone else's + site.

+
+ +
Solution:
+ +
+

This technique relies on the value of the + HTTP_REFERER variable, which is optional. As + such, it's possible for some people to circumvent this + limitation. However, most users will experience the failed + request, which should, over time, result in the image being + removed from that other site.

+

There are several ways that you can handle this + situation.

+ +

In this first example, we simply deny the request, if it didn't + initiate from a page on our site. For the purpose of this example, + we assume that our site is www.example.com.

+ + +RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ - [F,NC] + + +

In this second example, instead of failing the request, we display + an alternate image instead.

+ + +RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ /images/go-away.png [R,NC] + + +

In the third example, we redirect the request to an image on some + other site.

+ + +RewriteCond %{HTTP_REFERER} !^$
+RewriteCond %{HTTP_REFERER} !www.example.com [NC]
+RewriteRule \.(gif|jpg|png)$ http://other.example.com/image.gif [R,NC] + + +

Of these techniques, the last two tend to be the most effective + in getting people to stop hotlinking your images, because they will + simply not see the image that they expected to see.

+ +
+ +
Discussion:
+ +
+

If all you wish to do is deny access to the resource, rather + than redirecting that request elsewhere, this can be + accomplished without the use of mod_rewrite:

+ + + SetEnvIf Referer example\.com localreferer
+ <FilesMatch \.(jpg|png|gif)$>
+ Order deny,allow
+ Deny from all
+ Allow from env=localreferer
+ </FilesMatch> + +
+
+ +
+ +
+ + Blocking of Robots + +
+
Description:
+ +
+

+ In this recipe, we discuss how to block persistent requests from + a particular robot, or user agent.

+ +

The standard for robot exclusion defines a file, + /robots.txt that specifies those portions of your + website where you which to exclude robots. However, some robots + do not honor these files. +

+ +

Note that there are methods of accomplishing this which do + not use mod_rewrite. Note also that any technique that relies on + the clients USER_AGENT string can be circumvented + very easily, since that string can be changed.

+
+ +
Solution:
+ +
+

We use a ruleset that specifies the directory to be + protected, and the client USER_AGENT that + identifies the malicious or persistent robot.

+ +

In this example, we are blocking a robot called + NameOfBadRobot from a location + /secret/files. You may also specify an IP address + range, if you are trying to block that user agent only from the + particular source.

+ + +RewriteCond %{HTTP_USER_AGENT} ^NameOfBadRobot
+RewriteCond %{REMOTE_ADDR} =123\.45\.67\.[8-9]
+RewriteRule ^/secret/files/ - [F] + +
+ +
Discussion:
+ +
+

+ Rather than using mod_rewrite for this, you can accomplish the + same end using alternate means, as illustrated here: +

+ + SetEnvIfNoCase User-Agent ^NameOfBadRobot goaway
+ <Location /secret/files>
+ Order allow,deny
+ Allow from all
+ Deny from env=goaway
+ </Location> + +

+ As noted above, this technique is trivial to circumvent, by simply + modifying the USER_AGENT request header. If you + are experiencing a sustained attack, you should consider blocking + it at a higher level, such as at your firewall. +

+ +
+ +
+ +
+ +
+ + Denying Hosts in a Blacklist + +
+
Description:
+ +
+

We wish to maintain a blacklist of hosts, rather like + hosts.deny, and have those hosts blocked from + accessing our server.

+
+ +
Solution:
+ +
+ +RewriteEngine on
+RewriteMap hosts-deny txt:/path/to/hosts.deny
+RewriteCond ${hosts-deny:%{REMOTE_ADDR}|NOT-FOUND} !=NOT-FOUND [OR]
+RewriteCond ${hosts-deny:%{REMOTE_HOST}|NOT-FOUND} !=NOT-FOUND
+RewriteRule ^ - [F] + + + +##
+## hosts.deny
+##
+## ATTENTION! This is a map, not a list, even when we treat it as such.
+## mod_rewrite parses it for key/value pairs, so at least a
+## dummy value "-" must be present for each entry.
+##
+
+193.102.180.41 -
+bsdti1.sdm.de -
+192.76.162.40 -
+ +
+ +
Discussion:
+
+

+ The second RewriteCond assumes that you have HostNameLookups turned + on, so that client IP addresses will be resolved. If that's not the + case, you should drop the second RewriteCond, and drop the + [OR] flag from the first RewriteCond. +

+
+
+ +
+ +
+ + Referer-based Deflector + +
+
Description:
+ +
+

Redirect requests based on the Referer from which the request + came, with different targets per Referer.

+
+ +
Solution:
+ +
+

The following ruleset uses a map file to associate each Referer + with a redirection target.

+ + +RewriteMap deflector txt:/path/to/deflector.map
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}} =-
+RewriteRule ^ %{HTTP_REFERER} [R,L]
+
+RewriteCond %{HTTP_REFERER} !=""
+RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND
+RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L] + + +

The map file lists redirection targets for each referer, or, if + we just wish to redirect back to where they came from, a "-" is + placed in the map:

+ + +##
+## deflector.map
+##
+
+http://badguys.example.com/bad/index.html -
+http://badguys.example.com/bad/index2.html -
+http://badguys.example.com/bad/index3.html http://somewhere.example.com/ + + +
+
+ +
+ + Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml.meta URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml.meta?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml.meta (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/access.xml.meta Fri Mar 18 13:37:20 2011 @@ -0,0 +1,12 @@ + + + + + access + /rewrite/ + .. + + + en + + Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html Fri Mar 18 13:37:20 2011 @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: advanced.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html.en URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html.en?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html.en (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.html.en Fri Mar 18 13:37:20 2011 @@ -0,0 +1,492 @@ + + + +Advanced Techniques with mod_rewrite - Apache HTTP Server + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.2

+
+
<-
+

Advanced Techniques with mod_rewrite

+
+

Available Languages:  en 

+
+ + +

This document supplements the mod_rewrite +reference documentation. It provides +a few advanced techniques and tricks 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.
+ +
+ +
top
+
+

URL-based sharding accross 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
+: : +

+ +

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 +

+
+
+ +
top
+
+

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_FILENAME} !-s
+RewriteRule ^page\.html$ page.cgi [T=application/x-httpd-cgi,L] +

+ +

Here a request for page.html leads to an + internal run of a corresponding page.cgi if + page.html is missing or has filesize + null. The trick here is that page.cgi is a + CGI script which (additionally to its STDOUT) + writes its output to the file page.html. + Once it has completed, the server sends out + page.html. When the webmaster wants to force + a refresh of the contents, he just removes + page.html (typically from cron).

+
+
+ +
top
+
+

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.

+
+
+ +
top
+
+

Document With Autorefresh

+ + + +
+
Description:
+ +
+

Wouldn't it be nice, while creating a complex web page, if + the web browser would automatically refresh the page every + time we save a new version from within our editor? + Impossible?

+
+ +
Solution:
+ +
+

No! We just combine the MIME multipart feature, the + web server NPH feature, and the URL manipulation power of + mod_rewrite. First, we establish a new + URL feature: Adding just :refresh to any + URL causes the 'page' to be refreshed every time it is + updated on the filesystem.

+ +

+RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1 +

+ +

Now when we reference the URL

+ +

+/u/foo/bar/page.html:refresh +

+ +

this leads to the internal invocation of the URL

+ +

+/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html +

+ +

The only missing part is the NPH-CGI script. Although + one would usually say "left as an exercise to the reader" + ;-) I will provide this, too.

+ +
+#!/sw/bin/perl
+##
+##  nph-refresh -- NPH/CGI script for auto refreshing pages
+##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
+##
+$| = 1;
+
+#   split the QUERY_STRING variable
+@pairs = split(/&/, $ENV{'QUERY_STRING'});
+foreach $pair (@pairs) {
+($name, $value) = split(/=/, $pair);
+$name =~ tr/A-Z/a-z/;
+$name = 'QS_' . $name;
+$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
+eval "\$$name = \"$value\"";
+}
+$QS_s = 1 if ($QS_s eq '');
+$QS_n = 3600 if ($QS_n eq '');
+if ($QS_f eq '') {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
+exit(0);
+}
+if (! -f $QS_f) {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
+exit(0);
+}
+
+sub print_http_headers_multipart_begin {
+print "HTTP/1.0 200 OK\n";
+$bound = "ThisRandomString12345";
+print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
+&print_http_headers_multipart_next;
+}
+
+sub print_http_headers_multipart_next {
+print "\n--$bound\n";
+}
+
+sub print_http_headers_multipart_end {
+print "\n--$bound--\n";
+}
+
+sub displayhtml {
+local($buffer) = @_;
+$len = length($buffer);
+print "Content-type: text/html\n";
+print "Content-length: $len\n\n";
+print $buffer;
+}
+
+sub readfile {
+local($file) = @_;
+local(*FP, $size, $buffer, $bytes);
+($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
+$size = sprintf("%d", $size);
+open(FP, "&lt;$file");
+$bytes = sysread(FP, $buffer, $size);
+close(FP);
+return $buffer;
+}
+
+$buffer = &readfile($QS_f);
+&print_http_headers_multipart_begin;
+&displayhtml($buffer);
+
+sub mystat {
+local($file) = $_[0];
+local($time);
+
+($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
+return $mtime;
+}
+
+$mtimeL = &mystat($QS_f);
+$mtime = $mtime;
+for ($n = 0; $n &lt; $QS_n; $n++) {
+while (1) {
+    $mtime = &mystat($QS_f);
+    if ($mtime ne $mtimeL) {
+        $mtimeL = $mtime;
+        sleep(2);
+        $buffer = &readfile($QS_f);
+        &print_http_headers_multipart_next;
+        &displayhtml($buffer);
+        sleep(5);
+        $mtimeL = &mystat($QS_f);
+        last;
+    }
+    sleep($QS_s);
+}
+}
+
+&print_http_headers_multipart_end;
+
+exit(0);
+
+##EOF##
+
+
+
+ +
top
+
+

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 +

+
+
+ +
top
+
+

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

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

Set Environment Variables Based On URL Parts

+ + + +
+
Description:
+ +
+

At time, 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 can 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 +

+ +
+
+ +
+
+

Available Languages:  en 

+
+ \ No newline at end of file Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml Fri Mar 18 13:37:20 2011 @@ -0,0 +1,493 @@ + + + + + + + + + Rewrite + +Advanced Techniques with mod_rewrite + + + +

This document supplements the mod_rewrite +reference documentation. It provides +a few advanced techniques and tricks 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. + + +Module documentation +mod_rewrite introduction +Redirection and remapping +Controlling access +Virtual hosts +Proxying +Using RewriteMap + +When not to use mod_rewrite + +
+ + URL-based sharding accross 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
+: : + + +

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 + +
+
+ +
+ +
+ + 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_FILENAME} !-s
+RewriteRule ^page\.html$ page.cgi [T=application/x-httpd-cgi,L] + + +

Here a request for page.html leads to an + internal run of a corresponding page.cgi if + page.html is missing or has filesize + null. The trick here is that page.cgi is a + CGI script which (additionally to its STDOUT) + writes its output to the file page.html. + Once it has completed, the server sends out + page.html. When the webmaster wants to force + a refresh of the contents, he just removes + page.html (typically from cron).

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

+
+
+ +
+ +
+ + Document With Autorefresh + +
+
Description:
+ +
+

Wouldn't it be nice, while creating a complex web page, if + the web browser would automatically refresh the page every + time we save a new version from within our editor? + Impossible?

+
+ +
Solution:
+ +
+

No! We just combine the MIME multipart feature, the + web server NPH feature, and the URL manipulation power of + mod_rewrite. First, we establish a new + URL feature: Adding just :refresh to any + URL causes the 'page' to be refreshed every time it is + updated on the filesystem.

+ + +RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1 + + +

Now when we reference the URL

+ + +/u/foo/bar/page.html:refresh + + +

this leads to the internal invocation of the URL

+ + +/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html + + +

The only missing part is the NPH-CGI script. Although + one would usually say "left as an exercise to the reader" + ;-) I will provide this, too.

+ +
+#!/sw/bin/perl
+##
+##  nph-refresh -- NPH/CGI script for auto refreshing pages
+##  Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.
+##
+$| = 1;
+
+#   split the QUERY_STRING variable
+@pairs = split(/&/, $ENV{'QUERY_STRING'});
+foreach $pair (@pairs) {
+($name, $value) = split(/=/, $pair);
+$name =~ tr/A-Z/a-z/;
+$name = 'QS_' . $name;
+$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
+eval "\$$name = \"$value\"";
+}
+$QS_s = 1 if ($QS_s eq '');
+$QS_n = 3600 if ($QS_n eq '');
+if ($QS_f eq '') {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: No file given\n";
+exit(0);
+}
+if (! -f $QS_f) {
+print "HTTP/1.0 200 OK\n";
+print "Content-type: text/html\n\n";
+print "&lt;b&gt;ERROR&lt;/b&gt;: File $QS_f not found\n";
+exit(0);
+}
+
+sub print_http_headers_multipart_begin {
+print "HTTP/1.0 200 OK\n";
+$bound = "ThisRandomString12345";
+print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";
+&print_http_headers_multipart_next;
+}
+
+sub print_http_headers_multipart_next {
+print "\n--$bound\n";
+}
+
+sub print_http_headers_multipart_end {
+print "\n--$bound--\n";
+}
+
+sub displayhtml {
+local($buffer) = @_;
+$len = length($buffer);
+print "Content-type: text/html\n";
+print "Content-length: $len\n\n";
+print $buffer;
+}
+
+sub readfile {
+local($file) = @_;
+local(*FP, $size, $buffer, $bytes);
+($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);
+$size = sprintf("%d", $size);
+open(FP, "&lt;$file");
+$bytes = sysread(FP, $buffer, $size);
+close(FP);
+return $buffer;
+}
+
+$buffer = &readfile($QS_f);
+&print_http_headers_multipart_begin;
+&displayhtml($buffer);
+
+sub mystat {
+local($file) = $_[0];
+local($time);
+
+($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);
+return $mtime;
+}
+
+$mtimeL = &mystat($QS_f);
+$mtime = $mtime;
+for ($n = 0; $n &lt; $QS_n; $n++) {
+while (1) {
+    $mtime = &mystat($QS_f);
+    if ($mtime ne $mtimeL) {
+        $mtimeL = $mtime;
+        sleep(2);
+        $buffer = &readfile($QS_f);
+        &print_http_headers_multipart_next;
+        &displayhtml($buffer);
+        sleep(5);
+        $mtimeL = &mystat($QS_f);
+        last;
+    }
+    sleep($QS_s);
+}
+}
+
+&print_http_headers_multipart_end;
+
+exit(0);
+
+##EOF##
+
 +
+
+ +
+ +
+ + 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 time, 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 can 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 + + +
+
+ +
+ + Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml.meta URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml.meta?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml.meta (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/advanced.xml.meta Fri Mar 18 13:37:20 2011 @@ -0,0 +1,12 @@ + + + + + advanced + /rewrite/ + .. + + + en + + Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html Fri Mar 18 13:37:20 2011 @@ -0,0 +1,5 @@ +# GENERATED FROM XML -- DO NOT EDIT + +URI: avoid.html.en +Content-Language: en +Content-type: text/html; charset=ISO-8859-1 Added: httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html.en URL: http://svn.apache.org/viewvc/httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html.en?rev=1082915&view=auto ============================================================================== --- httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html.en (added) +++ httpd/httpd/branches/2.2.x/docs/manual/rewrite/avoid.html.en Fri Mar 18 13:37:20 2011 @@ -0,0 +1,227 @@ + + + +When not to use mod_rewrite - Apache HTTP Server + + + + +
+

Modules | Directives | FAQ | Glossary | Sitemap

+

Apache HTTP Server Version 2.2

+
+
<-
+

When not to use mod_rewrite

+
+

Available Languages:  en 

+
+ + +

This document supplements the mod_rewrite +reference documentation. It describes +perhaps one of the most important concepts about mod_rewrite - namely, +when to avoid using it.

+ +

mod_rewrite should be considered a last resort, when other +alternatives are found wanting. Using it when there are simpler +alternatives leads to configurations which are confusing, fragile, and +hard to maintain. Understanding what other alternatives are available is +a very important step towards mod_rewrite mastery.

+ +

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.

+ +

The most common situation in which mod_rewrite is +the right tool is when the very best solution requires access to the +server configuration files, and you don't have that access. Some +configuration directives are only available in the server configuration +file. So if you are in a hosting situation where you only have .htaccess +files to work with, you may need to resort to +mod_rewrite.

+ +
+ +
top
+
+

Simple Redirection

+ + +

mod_alias provides the Redirect and RedirectMatch directives, which provide a +means to redirect one URL to another. This kind of simple redirection of +one URL, or a class of URLs, to somewhere else, should be accomplished +using these directives rather than RewriteRule. RedirectMatch +allows you to include a regular expression in your redirection criteria, +providing many of the benefits of using RewriteRule.

+ +

A common use for RewriteRule is to redirect an entire +class of URLs. For example, all URLs in the /one directory +must be redirected to http://one.example.com/, or perhaps +all http requests must be redirected to +https.

+ +

These situations are better handled by the Redirect +directive. Remember that Redirect preserves path +information. That is to say, a redirect for a URL /one will +also redirect all URLs under that, such as /one/two.html +and /one/three/four.html.

+ +

To redirect URLs under /one to +http://one.example.com, do the following:

+ +

+Redirect /one/ http://one.example.com/ +

+ +

To redirect http URLs to https, do the +following:

+ +

+<VirtualHost *:80> +ServerName www.example.com
+Redirect / https://www.example.com/
+</VirtualHost > +
+<VirtualHost *:443> +ServerName www.example.com
+
+# ... SSL configuration goes here
+</VirtualHost > +

+ +

The use of RewriteRule to perform this task may be +appropriate if there are other RewriteRule directives in +the same scope. This is because, when there are Redirect +and RewriteRule directives in the same scope, the +RewriteRule directives will run first, regardless of the +order of appearance in the configuration file.

+ +

In the case of the http-to-https redirection, the use of +RewriteRule would be appropriate if you don't have access +to the main server configuration file, and are obliged to perform this +task in a .htaccess file instead.

+ +
top
+
+

URL Aliasing

+

The Alias directive +provides mapping from a URI to a directory - usually a directory outside +of your DocumentRoot. Although it +is possible to perform this mapping with mod_rewrite, +Alias is the preferred method, for reasons of simplicity +and performance.

+ +

Using Alias

+Alias /cats /var/www/virtualhosts/felines/htdocs +

+ +

+The use of mod_rewrite to perform this mapping may be +appropriate when you do not have access to the server configuration +files. Alias may only be used in server or virtualhost context, and not +in a .htaccess file. +

+ +

Symbolic links would be another way to accomplish the same thing, if +you have Options FollowSymLinks enabled on your +server.

+
top
+
+

Virtual Hosting

+

Although it is possible to handle virtual hosts +with mod_rewrite, it is seldom the right way. Creating individual +<VirtualHost> blocks is almost always the right way to go. In the +event that you have an enormous number of virtual hosts, consider using +mod_vhost_alias to create these hosts automatically.

+ +

Third-party modules such as mod_macro are +also useful for creating a large number of virtual hosts dynamically.

+ +

Using mod_rewrite for vitualhost creation may be +appropriate if you are using a hosting service that does not provide +you access to the server configuration files, and you are therefore +restricted to configuration using .htaccess files.

+ +

See the virtual hosts with mod_rewrite +document for more details on how you might accomplish this if it still +seems like the right approach.

+ +
top
+
+

Simple Proxying

+ +

RewriteRule provides the [P] flag to pass rewritten URIs through +mod_proxy.

+ +

+RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P] +

+ +

However, in many cases, when there is no actual pattern matching +meeded, as in the example shown above, the ProxyPass directive is a better choice. +The example here could be rendered as:

+ +

+ProxyPass /images/ http://imageserver.local/images/ +

+ +

Note that whether you use RewriteRule or ProxyPass, you'll still need to use the +ProxyPassReverse directive to +catch redirects issued from the back-end server:

+ +

+ProxyPassReverse /images/ http://imageserver.local/images/ +

+ +

You may need to use RewriteRule instead when there are +other RewriteRules in effect in the same scope, as a +RewriteRule will usually take effect before a +ProxyPass, and so may preempt what you're trying to +accomplish.

+ +
top
+
+

Environment Variable Testing

+ +

mod_rewrite is frequently used to take a particular +action based on the presence or absense of a particular environment +variable or request header. This can be done more efficiently using the +<If>.

+ +

Consider, for example, the common scenario where +RewriteRule is used to enforce a canonical +hostname, such as www.example.com instead of +example.com. This can be done using the <If> direct, as shown here:

+ +

+<If "$req{Host} = 'example.com'">
+RedirectMatch (.*) http://www.example.com$1 +</If> +

+ +

This technique can be used to take actions based on any request +header, response header, or environment variable, replacing +mod_rewrite in many common scenarios.

+ +

See especially the expression evaluation +documentation for a overview of what types of expressions you can +use in <If> sections, and in certain other directives.

+ +
+
+

Available Languages:  en 

+
+ \ No newline at end of file