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

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <title>Using RewriteMap</title>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <summary>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

0a3142725875ea286597e083547d34d98f8c1f2drbowenparticular server configuration, so it's important that you understand

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenthem, rather than merely cutting and pasting the examples into your

365711300b7310a1efed8aa9f01492086882ba7crbowenconfiguration.</note>

365711300b7310a1efed8aa9f01492086882ba7crbowen

365711300b7310a1efed8aa9f01492086882ba7crbowen </summary>

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

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

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

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

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen <section id="introduction">

0a3142725875ea286597e083547d34d98f8c1f2drbowen <title>Introduction</title>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen <directive module="mod_rewrite">RewriteCond</directive> directives to

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen perform rewriting that is too complicated, or too specialized to be

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen the <directive module="mod_rewrite">RewriteMap</directive> reference

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen documentation.</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen follows:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen<example>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen directives later on. Arguments are passed to the map via the

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen following syntax:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p class="indent">

0a3142725875ea286597e083547d34d98f8c1f2drbowen <strong>

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </strong>

0a3142725875ea286597e083547d34d98f8c1f2drbowen </p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

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

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

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>For example, you might define a

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen <example>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen<example>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen</example>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenin the map:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen<example>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen <section id="txt">

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen a '#' character.</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen file.</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p class="indent">

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen # Comment line

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>When the RewriteMap is invoked the argument is looked for in the

0a3142725875ea286597e083547d34d98f8c1f2drbowen first argument of a line, and, if found, the substitution value is

0a3142725875ea286597e083547d34d98f8c1f2drbowen returned.</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen recipe:</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen the following:</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <pre>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen##

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowentelevision 993

0a3142725875ea286597e083547d34d98f8c1f2drbowenstereo 198

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenfishingrod 043

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenbasketball 418

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowentelephone 328

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</pre>

0a3142725875ea286597e083547d34d98f8c1f2drbowen </example>

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen pattern in order for it to match anything:

0a3142725875ea286597e083547d34d98f8c1f2drbowen <example>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </note>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <section id="rnd">

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>MapType: <code>rnd</code>, MapSource: Unix filesystem

0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>This is identical to the Standard Plain Text variant

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen above but with a special post-processing feature: After

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen looking up a value it is parsed according to contained

0a3142725875ea286597e083547d34d98f8c1f2drbowen ``<code>|</code>'' characters which have the meaning of

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen ``or''. In other words they indicate a set of

0a3142725875ea286597e083547d34d98f8c1f2drbowen alternatives from which the actual returned value is

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen chosen randomly. For example, you might use the following map

0a3142725875ea286597e083547d34d98f8c1f2drbowen file and directives to provide a random load balancing between

0a3142725875ea286597e083547d34d98f8c1f2drbowen several back-end server, via a reverse-proxy. Images are sent

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen else is sent to one of the 'dynamic' pool.</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>Example:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <title>Rewrite map file</title>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <pre>

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

0a3142725875ea286597e083547d34d98f8c1f2drbowen## map.txt -- rewriting map

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen##

0a3142725875ea286597e083547d34d98f8c1f2drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowenstatic www1|www2|www3|www4

0a3142725875ea286597e083547d34d98f8c1f2drbowendynamic www5|www6

0a3142725875ea286597e083547d34d98f8c1f2drbowen</pre>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <example><title>Configuration directives</title>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen<br/>

0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1

0a3142725875ea286597e083547d34d98f8c1f2drbowen[NC,P,L]<br/>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen</example>

0a3142725875ea286597e083547d34d98f8c1f2drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="dbm">

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>MapType:

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem

0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>Here the source is a binary format DBM file containing

0a3142725875ea286597e083547d34d98f8c1f2drbowen the same contents as a <em>Plain Text</em> format file, but

0a3142725875ea286597e083547d34d98f8c1f2drbowen in a special representation which is optimized for really

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or

0a3142725875ea286597e083547d34d98f8c1f2drbowen db depending on <a href="/install.html#dbm">compile-time

0a3142725875ea286597e083547d34d98f8c1f2drbowen settings</a>. If the <em>type</em> is omitted, the

0a3142725875ea286597e083547d34d98f8c1f2drbowen compile-time default will be chosen.</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>To create a dbm file from a source text file, use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>

0a3142725875ea286597e083547d34d98f8c1f2drbowen <example>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="int">

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <title>int: Internal Function</title>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen function</p>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen Currently you cannot create your own, but the following

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen functions already exist:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <ul>

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

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen Translates special characters in the key to

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen hex-encodings.</li>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen Translates hex-encodings in the key back to

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen special characters.</li>

0a3142725875ea286597e083547d34d98f8c1f2drbowen </ul>

0a3142725875ea286597e083547d34d98f8c1f2drbowen </section>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowen<p>Here the source is a program, not a map file. To

0a3142725875ea286597e083547d34d98f8c1f2drbowencreate it you can use a language of your choice, but

0a3142725875ea286597e083547d34d98f8c1f2drbowenthe result has to be an executable program (either

0a3142725875ea286597e083547d34d98f8c1f2drbowenobject-code or a script with the magic cookie trick

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowenis started, and then communicates with the rewriting engine

0a3142725875ea286597e083547d34d98f8c1f2drbowenvia its <code>stdin</code> and <code>stdout</code>

0a3142725875ea286597e083547d34d98f8c1f2drbowenfile-handles. For each map-function lookup it will

0a3142725875ea286597e083547d34d98f8c1f2drbowenreceive the key to lookup as a newline-terminated string

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

0a3142725875ea286597e083547d34d98f8c1f2drbowenlooked-up value as a newline-terminated string on

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen``<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>