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>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

0a3142725875ea286597e083547d34d98f8c1f2drbowenthem, rather than merely cutting and pasting the examples into your

0a3142725875ea286597e083547d34d98f8c1f2drbowenconfiguration.</note>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </summary>

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

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

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

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

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

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

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

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

365711300b7310a1efed8aa9f01492086882ba7crbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="introduction">

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <title>Introduction</title>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <p>

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

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <directive module="mod_rewrite">RewriteCond</directive> directives to

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen perform rewriting that is too complicated, or too specialized to be

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen the <directive module="mod_rewrite">RewriteMap</directive> reference

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen documentation.</p>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen follows:</p>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<example>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen</example>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen directives later on. Arguments are passed to the map via the

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen following syntax:</p>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p class="indent">

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <strong>

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </strong>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </p>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

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

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

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>For example, you might define a

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <example>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen </example>

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<example>

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen</example>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenin the map:</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<example>

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen</example>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen </section>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="txt">

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen a '#' character.</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen file.</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p class="indent">

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen # Comment line<br />

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>When the RewriteMap is invoked the argument is looked for in the

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen first argument of a line, and, if found, the substitution value is

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen returned.</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen recipe:</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen </example>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen the following:</p>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <pre>

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen## productmap.txt - Product to ID map file

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

0a3142725875ea286597e083547d34d98f8c1f2drbowen

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelevision 993

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenstereo 198

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenfishingrod 043

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenbasketball 418

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelephone 328

0a3142725875ea286597e083547d34d98f8c1f2drbowen</pre>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

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

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

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

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen pattern in order for it to match anything:

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <example>

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

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen </example>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen </note>

721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="rnd">

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

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

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen matched.</p>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen file and directives to provide a random load balancing between

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

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <pre>

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

0a3142725875ea286597e083547d34d98f8c1f2drbowen## map.txt -- rewriting map

0a3142725875ea286597e083547d34d98f8c1f2drbowen##

0a3142725875ea286597e083547d34d98f8c1f2drbowen

0a3142725875ea286597e083547d34d98f8c1f2drbowenstatic www1|www2|www3|www4

0a3142725875ea286597e083547d34d98f8c1f2drbowendynamic www5|www6

0a3142725875ea286597e083547d34d98f8c1f2drbowen</pre>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </example>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <br/>

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen </example>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen specified hostnames at random, which is then used in the

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

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

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

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

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen map file.</p>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <example>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowenstatic www1|www1|www2|www3|www4

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen </example>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="dbm">

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>MapType:

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen 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>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <example>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen</example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="int">

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen function</p>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen Currently you cannot create your own, but the following

0a3142725875ea286597e083547d34d98f8c1f2drbowen functions already exist:</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <ul>

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

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

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates special characters in the key to

0a3142725875ea286597e083547d34d98f8c1f2drbowen hex-encodings.</li>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates hex-encodings in the key back to

0a3142725875ea286597e083547d34d98f8c1f2drbowen special characters.</li>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </ul>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<p>Here the source is a program, not a map file. To

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowencreate it you can use a language of your choice, but

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenthe result has to be an executable program (either

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenobject-code or a script with the magic cookie trick

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenis started, and then communicates with the rewriting engine

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenvia its <code>stdin</code> and <code>stdout</code>

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenfile-handles. For each map-function lookup it will

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenreceive the key to lookup as a newline-terminated string

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenlooked-up value as a newline-terminated string on

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

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

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenwhich is required for reliable communication with the program.

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenThe mutex mechanism and lock file can be configured with the

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

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowencontext that does not have <directive>RewriteEngine</directive> set to

83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<code>on</code></p>.

0a3142725875ea286597e083547d34d98f8c1f2drbowen

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen#!/usr/bin/perl

0a3142725875ea286597e083547d34d98f8c1f2drbowen$| = 1;

0a3142725875ea286597e083547d34d98f8c1f2drbowenwhile (&lt;STDIN&gt;) {

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen print $_;

0a3142725875ea286597e083547d34d98f8c1f2drbowen}

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

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="dbd">

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenMapSource: An SQL SELECT statement that takes a single

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen argument and returns a single value.</p>

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

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

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenperformance penalty but responds immediately if the database

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

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenrestart.</p>

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

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenthe result set is used.</p>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <example><title>Example</title>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen</example>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <section id="summary">

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <title>Summary</title>

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen once. For each mapping-function use one

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowen per-directory context it is of course possible to

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

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

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

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

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

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

0a3142725875ea286597e083547d34d98f8c1f2drbowenonce!

0a3142725875ea286597e083547d34d98f8c1f2drbowen</note>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen </section>

d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</manualpage>