Apache HTTP Server Version 2.4
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.
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 RewriteMap
directive may not be
used in <Directory>
sections or
.htaccess
files. You must
declare the map in server or virtualhost context. You may use the map,
once created, in your RewriteRule
and
RewriteCond
directives in those
scopes. You just can't declare it in those scopes.
The sections that follow describe the various MapTypes that may be used, and give examples of each.
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:
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]
Please note that the example offered here is for
illustration purposes only, and is not a recommendation. If you want
to make URLs case-insensitive, consider using
mod_speling
instead.
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
.
.htaccess
file, you'll need to remove the leading slash from the rewrite
pattern in order for it to match anything:
RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
The looked-up keys are cached by httpd until the mtime
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
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
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"
Note that with some dbm types, more than one file is generated, with
a common base name. For example, you may have two files named
mapfile.map.dir
and mapfiile.map.pag
. This is
normal, and you need only use the base name mapfile.map
in
your RewriteMap
directive.
The looked-up keys are cached by httpd until the mtime
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
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 started as root.
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 $_; }
$| = 1;
This will
of course vary in other languages. Buffered I/O will cause httpd to wait
for the output, and so it will hang.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"
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.