The Definitive Guide to Apache mod_rewrite (eBook)

Rich Bowen is a world-recognized expert and member of the Apache Software Foundation. He has authored several books on Apache, and regularly contributes to the Apache Server documentation project.

Contents at a Glance 5
Contents 7
About the Author 13
Acknowledgments 14
Introduction 15
Who This Book Is For 15
How This Book Is Structured 15
Prerequisites 16
Downloading the Code 16
Contacting the Author 16
1 An Introduction to mod_ rewrite 17
When to Use mod_ rewrite 17
“ Clean” URLs 18
Mass Virtual Hosting 18
Site Rearrangement 19
Conditional Changes 19
Other Stuff 19
When Not to Use mod_ rewrite 20
Simple Redirection 20
More Complicated Redirects 21
Virtual Hosts 22
Other Stuff 22
Summary 22
2 Regular Expressions 23
The Building Blocks 23
Matching Anything (.) 25
Escaping Characters (/) 25
Anchoring Text to the Start and End (^ and $) 25
Matching One or More Characters (+) 26
Matching Zero or More Characters (*) 26
Greedy Matching 27
Making a Match Optional (?) 27
Grouping and Capturing ( () ) 27
Matching One of a Group of Characters ([ ]) 29
Negation (!) 29
Regex Examples 30
Email Address 30
Phone Number 31
Matching URIs 32
Regex Tools 34
Rebug 35
Regex Coach 36
Summary 36
3 Installing and Configuring mod_ rewrite 37
Third- Party Distributions 37
Installing mod_ rewrite 38
Static vs. Shared Objects 38
Installing from Source: Static 39
Installing from Source: Shared 39
Enabling mod_rewrite: Binary Installation 41
Testing Whether mod_rewrite Is Correctly Installed 43
If You’re Not the System Administrator 44
Enabling the RewriteLog 45
Summary 46
4 The RewriteRule Directive 47
Introducing RewriteRule 47
RewriteRule Syntax 48
RewriteRule Context 48
Rewrite Target 51
RewriteRule Flags 53
Summary 62
5 The RewriteCond Directive 63
RewriteCond Syntax 63
RewriteCond Variables 64
Time-Based Redirection 66
RewriteCond Additional Variables 68
Image Theft 69
RewriteCond Pattern 69
Examples 70
RewriteCond Modifier Flags 71
Looping 72
Summary 73
6 The RewriteMap Directive 75
RewriteMap Syntax 75
Map Types 75
txt Map Files 76
Randomized Rewrites 78
Hash-Type Maps 80
External Programs 82
Internal Functions 83
Summary 83
7 Basic Rewrites 85
Adjusting URLs 85
Problem: We Want to Rewrite Path Information to a Query String ( Example 1) 85
Problem: We Want to Rewrite Path Information to a Query String ( Example 2) 86
Problem: We Want to Rewrite Path Information to a Query String ( Example 3) 87
Problem: We Have More Than Nine Arguments 88
Renaming and Reorganization 89
Problem: We’ve Switched from ColdFusion to PHP, but We Want All Old URLs to Continue Working 89
Problem: We’re Looking in More Than One Place for a File 90
Problem: Some of Our Content Is on Another Server 91
Problem: We Require a Canonical Hostname 91
Problem: We’re Viewing the Wrong SSL Host 92
Problem: We Need to Force SSL 93
Summary 93
8 Conditional Rewrites 95
Looping 95
Date- and Time- Based Rewrites 97
Problem: We Want to Show a Competition Website Only During a Competition 97
Redirecting Based on Client Conditions 99
Problem: We Want to Redirect Users Based on Their Browser Type 99
Problem: We Want to Send External Users Elsewhere 100
Problem: We Want to Serve Different Content Based on the User’s Username 100
Problem: We Want to Force Users to Come Through the Front Door 101
Problem: We Want to Prevent Users from Uploading PHP Files to an Unload Area and Then Executing Them 102
Problem: The Client Certificate Validation Error Message Is Indecipherable 103
Summary 103
9 Access Control 105
When Not to Use mod_ rewrite 105
Address-Based Access Control 105
Environment Variable–Based Access Control 106
Access Control with mod_ rewrite 107
Problem: We Want to Deny Access to a Particular Directory 107
Problem: We Want to Deny Access to Several Directories at Once 109
Simple Client- Based Access Control 110
Problem: We Want to Block a Spider from Hammering Our Website 110
Problem: We Want to Prevent “Image Theft” 111
Summary 113
10 Virtual Hosts 115
Virtual Hosts the Old- Fashioned Way 115
Configuring Virtual Hosts with mod_ vhost_ alias 117
www.example.com works, but example.com Doesn’t 118
There Are Too Many Directories 119
This Approach Breaks My Other Virtual Hosts 120
Logging 120
It’s Too Inflexible 120
Mass Virtual Hosting with mod_ rewrite 120
Rewriting Virtual Hosts 121
Virtual Hosts with RewriteMap 124
Logging for Mass Virtual Hosts 125
Splitting the Log File 126
Using Piped Log Handlers 126
Summary 127
11 Proxying 129
Proxy Rewrite Rules 129
Security 130
Apache 1.3 131
Apache 2.0 131
Proxying Without mod_ rewrite 132
Proxying with mod_ rewrite 133
Proxying a Particular File Type 133
Proxying to an Application Server 134
Modifying Proxied Content 134
Excluding Content from the Proxy 135
Looking Somewhere Else 136
Summary 137
12 Debugging 139
RewriteLog 139
A Simple RewriteLog Example 140
Loop Avoidance 142
RewriteRule in .htaccess Files 144
Regex Building Tools 146
Summary 148
Appendix Additional Resources 149
Online Resources 149
Books 149
PCRE Documentation 150
Index 151

When Not to Use mod_rewrite (p. 4)

As important as knowing when and how to use mod_rewrite is having a firm grasp on what other tools Apache offers, so that you know when not to use mod_rewrite. All of mod_rewrite’s amazing power comes at the cost of performance. Running regular expressions consumes time and memory, and it’s ideal to avoid it if alternate approaches are available.

However, even when there are one or more alternate approaches, it is seldom the case that one option is clearly the best one to use all the time. There are always a number of factors that you need to consider.

Just as there are several categories in which mod_rewrite use tends to fall, there are also several categories into which common misuse of mod_rewrite falls, as we’ll cover in the following sections.

Simple Redirection
Probably the most common misuse of mod_rewrite is for simple redirection. Redirection is used when a client requests one URL, and we want to give them a different one instead. In many cases, this is a simple one-to-one mapping. That is, it could be a mapping of one URL to another URL, or perhaps one directory to another directory, and sometimes even a mapping of one virtual host to another one, or perhaps to another server entirely.

In each of these cases, the Redirect directive is sufficient. The syntax of the Redirect directive is as follows:

Redirect [Original] [Target]

where [Original] is the URL that was originally requested, and [Target] is the fully qualified URL to which you wish to redirect it. When the user requests the original URL, Apache will send a redirection message back to the browser, which will then request the new URL.

The address appearing in the address bar of the user’s browser will change to the new URL. This approach requires a second round-trip to the web server in order to retrieve the content. The advantage of this approach, in addition to simplicity, is that the new corrected URL is announced to the user (who may or may not notice), but also that an automated process such as a search engine indexer will update its records to reflect the new URL and stop requesting the old one.

Several examples of the Redirect directive follow:

Redirect /index.cfm http://www.example.com/index.php

In this example, only one possible URL is redirected. That is, if someone requests

http://www.example.com/index.cfm, they will be sent instead to

http://www.example.com/

index.php, but no other URLs will be affected.

In this next example, we’ve renamed our /pics/ directory to /images/ instead, and we want all requests for things in /pics/ to go to /images/ instead:

Redirect /pics/ http://www.example.com/images/