Using RewriteMap

This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, and provides examples of each of the various RewriteMap types.

Introduction

The RewriteMap directive defines an external function which can be called in the context of RewriteRule or RewriteCond directives to perform rewriting that is too complicated, or too specialized to be performed just by regular expressions. The source of this lookup can be any of the types listed in the sections below, and enumerated in the RewriteMap reference documentation.

The syntax of the RewriteMap directive is as follows:

RewriteMap MapName MapType:MapSource

The MapName is an arbitray name that you assign to the map, and which you will use in directives later on. Arguments are passed to the map via the following syntax:

${ MapName : LookupKey }
${ MapName : LookupKey | DefaultValue }

When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

For example, you can define a RewriteMap as:

RewriteMap examplemap "txt:/path/to/file/map.txt"

You would then be able to use this map in a RewriteRule as follows:

RewriteRule "^/ex/(.*)" "${examplemap:$1}"

A default value can be specified in the event that nothing is found in the map:

RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"

The sections that follow describe the various MapTypes that may be used, and give examples of each.

int: Internal Function

When a MapType of int is used, the MapSource is one of the available internal RewriteMap functions. Module authors can provide additional internal functions by registering them with the ap_register_rewrite_mapfunc API. The functions that are provided by default are:

• toupper:
  Converts the key to all upper case.
• tolower:
  Converts the key to all lower case.
• escape:
  Translates special characters in the key to hex-encodings.
• unescape:
  Translates hex-encodings in the key back to special characters.

To use one of these functions, create a RewriteMap referencing the int function, and then use that in your RewriteRule:

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower
RewriteRule "(.*)" "${lc:$1}" [R]

txt: Plain text maps

When a MapType of txt is used, the MapSource is a filesystem path to a plain-text mapping file, containing one space-separated key/value pair per line. Optionally, a line may contain a comment, starting with a '#' character.

A valid text rewrite map file will have the following syntax:

# Comment line
MatchingKey SubstValue
MatchingKey SubstValue # comment

When the RewriteMap is invoked the argument is looked for in the first argument of a line, and, if found, the substitution value is returned.

For example, we can use a mapfile to translate product names to product IDs for easier-to-remember URLs, using the following recipe:

Product to ID configuration

RewriteMap product2id "txt:/etc/apache2/productmap.txt"
RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

We assume here that the prods.php script knows what to do when it received an argument of id=NOTFOUND when a product is not found in the lookup map.

The file /etc/apache2/productmap.txt then contains the following:

##
## productmap.txt - Product to ID map file
##

television 993
stereo 198
fishingrod 043
basketball 418
telephone 328

Thus, when http://example.com/product/television is requested, the RewriteRule is applied, and the request is internally mapped to /prods.php?id=993.

RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]

rnd: Randomized Plain Text

When a MapType of rnd is used, the MapSource is a filesystem path to a plain-text mapping file, each line of which contains a key, and one or more values separated by |. One of these values will be chosen at random if the key is matched.

For example, you can use the following map file and directives to provide a random load balancing between several back-end servers, via a reverse-proxy. Images are sent to one of the servers in the 'static' pool, while everything else is sent to one of the 'dynamic' pool.

##
## map.txt -- rewriting map
##

static www1|www2|www3|www4
dynamic www5|www6

Configuration directives

RewriteMap servers "rnd:/path/to/file/map.txt"

RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1"  [NC,P,L]
RewriteRule "^/(.*)"                "http://${servers:dynamic}/$1" [P,L]

So, when an image is requested and the first of these rules is matched, RewriteMap looks up the string static in the map file, which returns one of the specified hostnames at random, which is then used in the RewriteRule target.

If you wanted to have one of the servers more likely to be chosen (for example, if one of the server has more memory than the others, and so can handle more requests) simply list it more times in the map file.

static www1|www1|www2|www3|www4

dbm: DBM Hash File

When a MapType of dbm is used, the MapSource is a filesystem path to a DBM database file containing key/value pairs to be used in the mapping. This works exactly the same way as the txt map, but is much faster, because a DBM is indexed, whereas a text file is not. This allows more rapid access to the desired key.

You may optionally specify a particular dbm type:

RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"

The type can be sdbm, gdbm, ndbm or db. However, it is recommended that you just use the httxt2dbm utility that is provided with Apache HTTP Server, as it will use the correct DBM library, matching the one that was used when httpd itself was built.

To create a dbm file, first create a text map file as described in the txt section. Then run httxt2dbm:

$ httxt2dbm -i mapfile.txt -o mapfile.map

You can then reference the resulting file in your RewriteMap directive:

RewriteMap mapname "dbm:/etc/apache/mapfile.map"

prg: External Rewriting Program

When a MapType of prg is used, the MapSource is a filesystem path to an executable program which will providing the mapping behavior. This can be a compiled binary file, or a program in an interpreted language such as Perl or Python.

This program is started once, when the Apache HTTP Server is started, and then communicates with the rewriting engine via STDIN and STDOUT. That is, for each map function lookup, it expects one argument via STDIN, and should return one new-line terminated response string on STDOUT. If there is no corresponding lookup value, the map program should return the four-character string "NULL" to indicate this.

External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on.

By default, external rewriting programs are run as the user:group who started httpd. This can be changed on UNIX systems by passing user name and group name as third argument to RewriteMap in the username:groupname format.

This feature utilizes the rewrite-map mutex, which is required for reliable communication with the program. The mutex mechanism and lock file can be configured with the Mutex directive.

A simple example is shown here which will replace all dashes with underscores in a request URI.

Rewrite configuration

RewriteMap d2u "prg:/www/bin/dash2under.pl" apache:apache
RewriteRule "-" "${d2u:%{REQUEST_URI}}"

dash2under.pl

#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
while (<STDIN>) {
    s/-/_/g; # Replace dashes with underscores
    print $_;
}

dbd or fastdbd: SQL Query

When a MapType of dbd or fastdbd is used, the MapSource is a SQL SELECT statement that takes a single argument and returns a single value.

mod_dbd will need to be configured to point at the right database for this statement to be executed.

There are two forms of this MapType. Using a MapType of dbd causes the query to be executed with each map request, while using fastdbd caches the database lookups internally. So, while fastdbd is more efficient, and therefore faster, it won't pick up on changes to the database until the server is restarted.

If a query returns more than one row, a random row from the result set is used.

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

Summary

The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its rewriting mapfile.

While you cannot declare a map in per-directory context (.htaccess files or <Directory> blocks) it is possible to use this map in per-directory context.