<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<manualpage metafile="rewritemap.xml.meta">

<parentdocument href="./">Rewrite</parentdocument>

<title>Using RewriteMap</title>

<summary>

<p>This document supplements the <module>mod_rewrite</module>

<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes

the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,

and provides examples of each of the various <code>RewriteMap</code> types.</p>

<note type="warning">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.</note>

</summary>

<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>

<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>

<seealso><a href="remapping.html">Redirection and remapping</a></seealso>

<seealso><a href="access.html">Controlling access</a></seealso>

<seealso><a href="vhosts.html">Virtual hosts</a></seealso>

<seealso><a href="proxy.html">Proxying</a></seealso>

<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>

<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>

<section id="introduction">

<title>Introduction</title>

<p>

The <directive module="mod_rewrite">RewriteMap</directive> directive

defines an external function which can be called in the context of

<directive module="mod_rewrite">RewriteRule</directive> or

<directive module="mod_rewrite">RewriteCond</directive> 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 <directive module="mod_rewrite">RewriteMap</directive> reference

documentation.</p>

<p>The syntax of the <code>RewriteMap</code> directive is as

follows:</p>

<example>

RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>

</example>

<p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> 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:</p>

<p class="indent">

<strong>

<code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>

<code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>

<em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>

</strong>

</p>

<p>When such a construct occurs, the map <em>MapName</em> is

consulted and the key <em>LookupKey</em> is looked-up. If the

key is found, the map-function construct is substituted by

<em>SubstValue</em>. If the key is not found then it is

substituted by <em>DefaultValue</em> or by the empty string

if no <em>DefaultValue</em> was specified.</p>

<p>For example, you might define a

<directive>RewriteMap</directive> as:</p>

<example>

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

</example>

<p>You would then be able to use this map in a

<directive>RewriteRule</directive> as follows:</p>

<example>

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

</example>

<p>A default value can be specified in the event that nothing is found

in the map:</p>

<example>

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

</example>

<p>The sections that follow describe the various <em>MapType</em>s that

may be used, and give examples of each.</p>

</section>

<section id="txt">

<title>txt: Plain text maps</title>

<p>When a MapType of <code>txt</code>is used, the MapSource is a filesystem path to a

plain-text mapping file, containing space-separated key/value pair

per line. Optionally, a line may be contain a comment, starting with

a '#' character.</p>

<p>For example, the following might be valid entries in a map

file.</p>

<p class="indent">

# Comment line<br />

<strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />

<strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />

</p>

<p>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.</p>

<p>For example, we might use a mapfile to translate product names to

product IDs for easier-to-remember URLs, using the following

recipe:</p>

<example><title>Product to ID configuration</title>

RewriteMap product2id txt:/etc/apache2/productmap.txt<br />

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

</example>

<p>We assume here that the <code>prods.php</code> script knows what

to do when it received an argument of <code>id=NOTFOUND</code> when

a product is not found in the lookup map.</p>

<p>The file <code>/etc/apache2/productmap.txt</code> then contains

the following:</p>

<example><title>Product to ID map</title>

<pre>

##

## productmap.txt - Product to ID map file

##

television 993

stereo 198

fishingrod 043

basketball 418

telephone 328

</pre>

</example>

<p>Thus, when <code>http://example.com/product/television</code> is

requested, the <code>RewriteRule</code> is applied, and the request

is internally mapped to <code>/prods.php?id=993</code>.</p>

<note><title>Note: .htaccess files</title>

The example given is crafted to be used in server or virtualhost

scope. If you're planning to use this in a <code>.htaccess</code>

file, you'll need to remove the leading slash from the rewrite

pattern in order for it to match anything:

<example>

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

</example>

</note>

</section>

<section id="rnd">

<title>rnd: Randomized Plain Text</title>

<p>When a MapType of <code>rnd</code> 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 <code>|</code>.

One of these values will be chosen at random if the key is

matched.</p>

<p>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.</p>

<example><title>Rewrite map file</title>

<pre>

##

## map.txt -- rewriting map

##

static www1|www2|www3|www4

dynamic www5|www6

</pre>

</example>

<example><title>Configuration directives</title>

RewriteMap servers rnd:/path/to/file/map.txt<br/>

<br/>

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

RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]

</example>

<p>So, when an image is requested and the first of these rules is

matched, <code>RewriteMap</code> looks up the string

<code>static</code> in the map file, which returns one of the

specified hostnames at random, which is then used in the

<code>RewriteRule</code> target.</p>

<p>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.</p>

<example>

static www1|www1|www2|www3|www4

</example>

</section>

<section id="dbm">

<title>dbm: DBM Hash File</title>

<p>When a MapType of <code>dbm</code> 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

<code>txt</code> 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.</p>

<p>You may optionally specify a particular dbm type:</p>

<example>

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

</example>

<p>The type can be sdbm, gdbm, ndbm or db.

However, it is recommended that you just use the <a

href="/programs/httxt2dbm.html">httxt2dbm</a> 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.</p>

<p>To create a dbm file, first create a text map file as described

in the <a href="#txt">txt</a> section. Then run

<code>httxt2dbm</code>:</p>

<example>

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

</example>

<p>You can then reference the resulting file in your

<code>RewriteMap</code> directive:</p>

<example>

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

</example>

<note>

<p>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

<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is

normal, and you need only use the base name <code>mapfile.map</code> in

your <code>RewriteMap</code> directive.</p>

</note>

</section>

<section id="int">

<title>int: Internal Function</title>

<p>

MapType: <code>int</code>, MapSource: Internal Apache httpd

function</p>

<p>Here, the source is an internal Apache httpd function.

Currently you cannot create your own, but the following

functions already exist:</p>

<ul>

<li><strong>toupper</strong>:<br/>

Converts the key to all upper case.</li>

<li><strong>tolower</strong>:<br/>

Converts the key to all lower case.</li>

<li><strong>escape</strong>:<br/>

Translates special characters in the key to

hex-encodings.</li>

<li><strong>unescape</strong>:<br/>

Translates hex-encodings in the key back to

special characters.</li>

</ul>

</section>

<section id="prg"><title>prg: External Rewriting Program</title>

<p>MapType: <code>prg</code>, MapSource: Unix filesystem path to valid regular file </p>

<p>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

'<code>#!/path/to/interpreter</code>' as the first

line).</p><p>This program is started once, when the Apache httpd server

is started, and then communicates with the rewriting engine

via its <code>stdin</code> and <code>stdout</code>

file-handles. For each map-function lookup it will

receive the key to lookup as a newline-terminated string

on <code>stdin</code>. It then has to give back the

looked-up value as a newline-terminated string on

<code>stdout</code> or the four-character string

``<code>NULL</code>'' if it fails (<em>i.e.</em>, there

is no corresponding value for the given key).</p><p>This feature utilizes the <code>rewrite-map</code> mutex,

which is required for reliable communication with the program.

The mutex mechanism and lock file can be configured with the

<directive module="core">Mutex</directive> directive.</p><p>External rewriting programs are not started if they're defined in a

context that does not have <directive>RewriteEngine</directive> set to

<code>on</code></p>.

<p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,

key == value) could be:</p><example><pre>

#!/usr/bin/perl

$| = 1;

while (&lt;STDIN&gt;) {

# ...put here any transformations or lookups...

print $_;

}

</pre></example><p>But be very careful:</p><ol><li>``<em>Keep it simple, stupid</em>'' (KISS).

If this program hangs, it will cause Apache httpd to hang

when trying to use the relevant rewrite rule.</li><li>A common mistake is to use buffered I/O on

<code>stdout</code>. Avoid this, as it will cause a deadloop!

``<code>$|=1</code>'' is used above, to prevent this.</li></ol></section>

<section id="dbd">

<title>dbd or fastdbd: SQL Query</title>

<p>MapType: <code>dbd</code> or <code>fastdbd</code>,

MapSource: An SQL SELECT statement that takes a single

argument and returns a single value.</p>

<p>This uses <module>mod_dbd</module> to implement a rewritemap

by lookup in an SQL database. There are two forms:

<code>fastdbd</code> caches database lookups internally,

<code>dbd</code> doesn't. So <code>dbd</code> incurs a

performance penalty but responds immediately if the database

contents are updated, while <code>fastdbd</code> is more

efficient but won't re-read database contents until server

restart.</p>

<p>If a query returns more than one row, a random row from

the result set is used.</p>

<example><title>Example</title>

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

</example>

</section>

<section id="summary">

<title>Summary</title>

<p>The <directive>RewriteMap</directive> directive can occur more than

once. For each mapping-function use one

<directive>RewriteMap</directive> directive to declare its rewriting

mapfile. While you cannot <strong>declare</strong> a map in

per-directory context it is of course possible to

<strong>use</strong> this map in per-directory context. </p>

<note><title>Note</title> For plain text and DBM format files the

looked-up keys are cached in-core until the <code>mtime</code> of the

mapfile changes or the server does a restart. This way you can have

map-functions in rules which are used for <strong>every</strong>

request. This is no problem, because the external lookup only happens

once!

</note>

</section>

</manualpage>