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

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

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

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

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

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen <title>Using RewriteMap</title>

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen <summary>

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen

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

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

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

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

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen <note type="warning">Note that many of these examples won't work unchanged in your

4a1711ab536d965e63d7be80e29f912287fe70b2rbowenparticular server configuration, so it's important that you understand

4a1711ab536d965e63d7be80e29f912287fe70b2rbowenthem, rather than merely cutting and pasting the examples into your

4a1711ab536d965e63d7be80e29f912287fe70b2rbowenconfiguration.</note>

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </summary>

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

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

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

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

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

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <section id="introduction">

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <title>Introduction</title>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <directive module="mod_rewrite">RewriteCond</directive> directives to

1a1f0f42c4b3840641897888fec7792af8ba384frbowen perform rewriting that is too complicated, or too specialized to be

1a1f0f42c4b3840641897888fec7792af8ba384frbowen performed just by regular expressions. The source of this lookup can

1a1f0f42c4b3840641897888fec7792af8ba384frbowen be any of the types listed in the sections below, and enumerated in

1a1f0f42c4b3840641897888fec7792af8ba384frbowen the <directive module="mod_rewrite">RewriteMap</directive> reference

1a1f0f42c4b3840641897888fec7792af8ba384frbowen documentation.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen follows:</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen</example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an

1a1f0f42c4b3840641897888fec7792af8ba384frbowen arbitray name that you assign to the map, and which you will use in

1a1f0f42c4b3840641897888fec7792af8ba384frbowen directives later on. Arguments are passed to the map via the

1a1f0f42c4b3840641897888fec7792af8ba384frbowen following syntax:</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p class="indent">

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <strong>

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </strong>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

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

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>For example, you might define a

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <example>

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </example>

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<example>

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen</example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowenin the map:</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<example>

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen</example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<note><title>Per-directory and .htaccess context</title>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowenThe <code>RewriteMap</code> directive may not be used in

1a1f0f42c4b3840641897888fec7792af8ba384frbowen&lt;Directory&gt; sections or <code>.htaccess</code> files. You must

1a1f0f42c4b3840641897888fec7792af8ba384frbowendeclare the map in server or virtualhost context. You may use the map,

1a1f0f42c4b3840641897888fec7792af8ba384frbowenonce created, in your <code>RewriteRule</code> and

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<code>RewriteCond</code> directives in those scopes. You just can't

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<strong>declare</strong> it in those scopes.

1a1f0f42c4b3840641897888fec7792af8ba384frbowen</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen</note>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </section>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <section id="txt">

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen a '#' character.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen file.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p class="indent">

1a1f0f42c4b3840641897888fec7792af8ba384frbowen # Comment line<br />

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>When the RewriteMap is invoked the argument is looked for in the

1a1f0f42c4b3840641897888fec7792af8ba384frbowen first argument of a line, and, if found, the substitution value is

1a1f0f42c4b3840641897888fec7792af8ba384frbowen returned.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen recipe:</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen the following:</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen##<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen## productmap.txt - Product to ID map file<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen##<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowentelevision 993<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenstereo 198<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenfishingrod 043<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenbasketball 418<br />

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowentelephone 328

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

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

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen pattern in order for it to match anything:

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <example>

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </note>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <note><title>Cached lookups</title>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen The looked-up keys are cached by httpd until the <code>mtime</code>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen (modified time) of the mapfile changes, or the httpd server is

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen restarted. This ensures better performance on maps that are called

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen by many requests.

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </note>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </section>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <section id="rnd">

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>When a MapType of <code>rnd</code> is used, the MapSource is a

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen filesystem path to a plain-text mapping file, each line of which

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen contains a key, and one or more values separated by <code>|</code>.

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen matched.</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>For example, you might use the following map

1a1f0f42c4b3840641897888fec7792af8ba384frbowen file and directives to provide a random load balancing between

1a1f0f42c4b3840641897888fec7792af8ba384frbowen several back-end server, via a reverse-proxy. Images are sent

1a1f0f42c4b3840641897888fec7792af8ba384frbowen to one of the servers in the 'static' pool, while everything

1a1f0f42c4b3840641897888fec7792af8ba384frbowen else is sent to one of the 'dynamic' pool.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen##<br />

1a1f0f42c4b3840641897888fec7792af8ba384frbowen## map.txt -- rewriting map<br />

1a1f0f42c4b3840641897888fec7792af8ba384frbowen##<br />

1a1f0f42c4b3840641897888fec7792af8ba384frbowen<br />

1a1f0f42c4b3840641897888fec7792af8ba384frbowenstatic www1|www2|www3|www4<br />

1a1f0f42c4b3840641897888fec7792af8ba384frbowendynamic www5|www6

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <example><title>Configuration directives</title>

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <br/>

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

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

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen specified hostnames at random, which is then used in the

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>If you wanted to have one of the servers more likely to be chosen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen (for example, if one of the server has more memory than the others,

1a1f0f42c4b3840641897888fec7792af8ba384frbowen and so can handle more requests) simply list it more times in the

1a1f0f42c4b3840641897888fec7792af8ba384frbowen map file.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowenstatic www1|www1|www2|www3|www4

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </example>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen </section>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <section id="dbm">

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

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>When a MapType of <code>dbm</code> is used, the MapSource is a

1a1f0f42c4b3840641897888fec7792af8ba384frbowen filesystem path to a DBM database file containing key/value pairs to

1a1f0f42c4b3840641897888fec7792af8ba384frbowen be used in the mapping. This works exactly the same way as the

1a1f0f42c4b3840641897888fec7792af8ba384frbowen <code>txt</code> map, but is much faster, because a DBM is indexed,

1a1f0f42c4b3840641897888fec7792af8ba384frbowen whereas a text file is not. This allows more rapid access to the

1a1f0f42c4b3840641897888fec7792af8ba384frbowen desired key.</p>

1a1f0f42c4b3840641897888fec7792af8ba384frbowen

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <example>

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen provided with Apache HTTP Server, as it will use the correct DBM library,

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen matching the one that was used when httpd itself was built.</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <code>httxt2dbm</code>:</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<example>

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen</example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteMap mapname dbm:/etc/apache/mapfile.map

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen</example>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<note>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<p>Note that with some dbm types, more than one file is generated, with

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowena common base name. For example, you may have two files named

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

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

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenyour <code>RewriteMap</code> directive.</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen</note>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<note><title>Cached lookups</title>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen<p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenThe looked-up keys are cached by httpd until the <code>mtime</code>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen(modified time) of the mapfile changes, or the httpd server is

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenrestarted. This ensures better performance on maps that are called

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenby many requests.

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen</p>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen</note>

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen

13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen </section>

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen

4a1711ab536d965e63d7be80e29f912287fe70b2rbowen <section id="int">

<title>int: Internal Function</title>

<p>When a MapType of <code>int</code> is used, the MapSource is one

of the available internal RewriteMap functions. Module authors can provide

additional internal functions by registering them with the

<code>ap_register_rewrite_mapfunc</code> API.

The functions that are provided by default are:

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

<p>

To use one of these functions, create a <code>RewriteMap</code> referencing

the int function, and then use that in your <code>RewriteRule</code>:

</p>

<example><title>Redirect a URI to an all-lowercase version of itself</title>

RewriteMap lc int:tolower<br />

RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]

</example>

<note>

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

<module>mod_speling</module> instead.

</p>

</note>

</section>

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

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

<p>This program is started once, when the Apache HTTP Server is

started, and then communicates with the rewriting engine via

<code>STDIN</code> and <code>STDOUT</code>. That is, for each map

function lookup, it expects one argument via <code>STDIN</code>, and

should return one new-line terminated response string on

<code>STDOUT</code>. If there is no corresponding lookup value, the

map program should return the four-character string

"<code>NULL</code>" to indicate this.</p>

<p>External rewriting programs are not started if they're defined in

a context that does not have <directive

module="mod_rewrite">RewriteEngine</directive> set to

<code>on</code>.</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>A simple example is shown here which will replace all dashes with

underscores in a request URI.</p>

<example><title>Rewrite configuration</title>

RewriteMap d2u prg:/www/bin/dash2under.pl<br />

RewriteRule - ${d2u:%{REQUEST_URI}}

</example>

<example><title>dash2under.pl</title>

#!/usr/bin/perl<br />

$| = 1; # Turn off I/O buffering<br />

while (&lt;STDIN&gt;) {<br />

<indent>

s/-/_/g; # Replace dashes with underscores<br />

print $_;<br />

</indent>

}<br />

</example>

<note><title>Caution!</title>

<ul>

<li>Keep your rewrite map program as simple as possible. If the program

hangs, it will cause httpd to wait indefinitely for a response from the

map, which will, in turn, cause httpd to stop responding to

requests.</li>

<li>Be sure to turn off buffering in your program. In Perl this is done

by the second line in the example script: <code>$| = 1;</code> This will

of course vary in other languages. Buffered I/O will cause httpd to wait

for the output, and so it will hang.</li>

<li>Remember that there is only one copy of the program, started at

server startup. All requests will need to go through this one bottleneck.

This can cause significant slowdowns if many requests must go through

this process, or if the script itself is very slow.</li>

</ul>

</note>

</section>

<section id="dbd">

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

<p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is

used, the MapSource is a SQL SELECT statement that takes a single

argument and returns a single value.</p>

<p><module>mod_dbd</module> will need to be configured to point at

the right database for this statement to be executed.</p>

<p>There are two forms of this MapType.

Using a MapType of <code>dbd</code> causes the query to be

executed with each map request, while using <code>fastdbd</code>

caches the database lookups internally. So, while

<code>fastdbd</code> is more efficient, and therefore faster, it

won't pick up on changes to the database until the server is

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

<p>While you cannot <strong>declare</strong> a map in

per-directory context (<code>.htaccess</code> files or

&lt;Directory&gt; blocks) it is possible to

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

</section>

</manualpage>