Map Type	Description
`txt`	A plain text file containing space-separated key-value + pairs, one per line.	Details ...
`rnd`	Randomly selects an entry from a plain text file	Details ...
`dbm`	Looks up an entry in a dbm file containing name, value + pairs. Hash is constructed from a plain text file format using + the `httxt2dbm` + utility.	Details ...
`int`	One of the four available internal functions provided by + `RewriteMap`: toupper, tolower, escape or + unescape.	Details ...
`prg`	Calls an external program or script to process the + rewriting.	Details ...
`dbd` or `fastdbd`	A SQL SELECT statement to be performed to look up the + rewrite target.	Details ...

Map Type

Description

txt

A plain text file containing space-separated key-value + pairs, one per line.

rnd

Randomly selects an entry from a plain text file

dbm

Looks up an entry in a dbm file containing name, value + pairs. Hash is constructed from a plain text file format using + the httxt2dbm + utility.

Details ...

int

One of the four available internal functions provided by + RewriteMap: toupper, tolower, escape or + unescape.

Details ...

prg

Calls an external program or script to process the + rewriting.

Details ...

dbd or fastdbd

A SQL SELECT statement to be performed to look up the + rewrite target.

Details ...

Here, the source is an internal Apache httpd function. - Currently you cannot create your own, but the following - functions already exist:

Map Type	Description
`txt`	A plain text file containing space-separated key-value + pairs, one per line.	Details ...
`rnd`	Randomly selects an entry from a plain text file	Details ...
`dbm`	Looks up an entry in a dbm file containing name, value + pairs. Hash is constructed from a plain text file format using + the `httxt2dbm` + utility.	Details ...
`int`	One of the four available internal functions provided by + `RewriteMap`: toupper, tolower, escape or + unescape.	Details ...
`prg`	Calls an external program or script to process the + rewriting.	Details ...
`dbd` or `fastdbd`	A SQL SELECT statement to be performed to look up the + rewrite target.	Details ...

Map Type

Description

txt

A plain text file containing space-separated key-value + pairs, one per line.

Details ...

rnd

Randomly selects an entry from a plain text file

Details ...

dbm

Looks up an entry in a dbm file containing name, value + pairs. Hash is constructed from a plain text file format using + the httxt2dbm + utility.

Details ...

int

One of the four available internal functions provided by + RewriteMap: toupper, tolower, escape or + unescape.

Details ...

prg

Calls an external program or script to process the + rewriting.

Details ...

dbd or fastdbd

A SQL SELECT statement to be performed to look up the + rewrite target.

Details ...

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 it is of course possible to - use this map in per-directory context.

Using RewriteMap

Available Languages: en

+ + +

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.

+ +

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.

+ +

Introduction
txt: Plain text maps
Randomized Plain Text
DBM Hash File
Internal Function
External Rewriting Program
SQL Query
Summary

Introduction

+ +

The RewriteMap directive defines a + Rewriting Map which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.

+ +

The MapName is + the name of the map and will be used to specify a + mapping-function for the substitution strings of a rewriting + rule via one of the following constructs:

+ +

+ ${ 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 might 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} +

+ +

The following combinations for MapType and + MapSource can be used:

txt: Plain text maps

+ +

MapType: txt, MapSource: Unix filesystem + path to valid regular file

+ +

This is the standard rewriting map feature where the + MapSource is a plain ASCII file containing + either blank lines, comment lines (starting with a '#' + character) or pairs like the following - one per + line.

+ +

+ MatchingKey + SubstValue +

+ +

Example

+##
+##  map.txt -- rewriting map
+##
+
+Ralf.S.Engelschall    rse   # Bastard Operator From Hell
+Mr.Joe.Average        joe   # Mr. Average
+

+ +

+RewriteMap real-to-user txt:/path/to/file/map.txt +

+ +

Randomized Plain Text

+ +

MapType: rnd, MapSource: Unix filesystem + path to valid regular file

+ +

This is identical to the Standard Plain Text variant + above but with a special post-processing feature: After + looking up a value it is parsed according to contained + ``|'' characters which have the meaning of + ``or''. In other words they indicate a set of + alternatives from which the actual returned value is + chosen randomly. For example, you might use the following map + file and directives to provide a random load balancing between + several back-end server, 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.

Example:

+ +

Rewrite map file

+##
+##  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] +

+ +

DBM Hash File

+ +

MapType: + dbm[=type], MapSource: Unix filesystem + path to valid regular file

+ +

Here the source is a binary format DBM file containing + the same contents as a Plain Text format file, but + in a special representation which is optimized for really + fast lookups. The type can be sdbm, gdbm, ndbm, or + db depending on compile-time + settings. If the type is omitted, the + compile-time default will be chosen.

+ +

To create a dbm file from a source text file, use the httxt2dbm utility.

+ +

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

Internal Function

+ MapType: int, MapSource: Internal Apache httpd + function

+ +

Here, the source is an internal Apache httpd function. + Currently you cannot create your own, but the following + functions already exist:

+ +

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.

External Rewriting Program

+ MapType: prg, MapSource: Unix filesystem + path to valid regular file +

+ +

Here the source is a program, not a map file. To + create it you can use a language of your choice, but + the result has to be an executable program (either + object-code or a script with the magic cookie trick + '#!/path/to/interpreter' as the first + line).

+ +

This program is started once, when the Apache httpd server + is started, and then communicates with the rewriting engine + via its stdin and stdout + file-handles. For each map-function lookup it will + receive the key to lookup as a newline-terminated string + on stdin. It then has to give back the + looked-up value as a newline-terminated string on + stdout or the four-character string + ``NULL'' if it fails (i.e., there + is no corresponding value for the given key).

+ +

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.

+ +

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

. + +

A trivial program which will implement a 1:1 map (i.e., + key == value) could be:

+ +

+#!/usr/bin/perl
+$| = 1;
+while (<STDIN>) {
+    # ...put here any transformations or lookups...
+    print $_;
+}
+

+ +

But be very careful:

+ +

``Keep it simple, stupid'' (KISS). + If this program hangs, it will cause Apache httpd to hang + when trying to use the relevant rewrite rule.
A common mistake is to use buffered I/O on + stdout. Avoid this, as it will cause a deadloop! + ``$|=1'' is used above, to prevent this.

SQL Query

MapType: dbd or fastdbd, + MapSource: An SQL SELECT statement that takes a single + argument and returns a single value.

+ +

This uses mod_dbd to implement a rewritemap + by lookup in an SQL database. There are two forms: + fastdbd caches database lookups internally, + dbd doesn't. So dbd incurs a + performance penalty but responds immediately if the database + contents are updated, while fastdbd is more + efficient but won't re-read database contents until server + restart.

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

Example

+ +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 it is of course possible to + use this map in per-directory context.

+ +

Note

For plain text and DBM format files the +looked-up keys are cached in-core until the mtime of the +mapfile changes or the server does a restart. This way you can have +map-functions in rules which are used for every +request. This is no problem, because the external lookup only happens +once! +

+ +

Example

Rewrite map file

Configuration directives

Example

Note

Using RewriteMap

See also

Example

Rewrite map file

Configuration directives

Example

Note