rewritemap.html.en revision 4bf04ac5fe6a2ae518bd0d8d463f069253d46c0a
97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml version="1.0" encoding="ISO-8859-1"?>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
97a9a944b5887e91042b019776c41d5dd74557aferikabele<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive This file is generated from xml source: DO NOT EDIT
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
fe64b2ba25510d8c9dba5560a2d537763566cf40nd -->
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Using RewriteMap - Apache HTTP Server</title>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<body id="manual-page"><div id="page-header">
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p class="apache">Apache HTTP Server Version 2.5</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<img alt="" src="/images/feather.gif" /></div>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<div id="path">
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="toplang">
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd</div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7ndthe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
660c7c6d7e175238807ffc144c0f8e746bf2cfb0minfrinand provides examples of each of the various <code>RewriteMap</code> types.</p>
7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <div class="warning">Note that many of these examples won't work unchanged in your
3b3b7fc78d1f5bfc2769903375050048ff41ff26ndparticular server configuration, so it's important that you understand
fe64b2ba25510d8c9dba5560a2d537763566cf40ndthem, rather than merely cutting and pasting the examples into your
fe64b2ba25510d8c9dba5560a2d537763566cf40ndconfiguration.</div>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd </div>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive</ul><h3>See also</h3><ul class="seealso"><li><a href="/mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="section">
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<h2><a name="introduction" id="introduction">Introduction</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive
f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
06ba4a61654b3763ad65f52283832ebf058fdf1cslive defines an external function which can be called in the context of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
136489fb8f0fe36dbcad3064a335eb86bfbeb5c6rbowen <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
97a9a944b5887e91042b019776c41d5dd74557aferikabele perform rewriting that is too complicated, or too specialized to be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive performed just by regular expressions. The source of this lookup can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive be any of the types listed in the sections below, and enumerated in
97a9a944b5887e91042b019776c41d5dd74557aferikabele the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
06ba4a61654b3763ad65f52283832ebf058fdf1cslive documentation.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The syntax of the <code>RewriteMap</code> directive is as
fe64b2ba25510d8c9dba5560a2d537763566cf40nd follows:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="example"><p><code>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd</code></p></div>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd
117c1f888a14e73cdd821dc6c23eb0411144a41cnd <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
117c1f888a14e73cdd821dc6c23eb0411144a41cnd arbitray name that you assign to the map, and which you will use in
fe64b2ba25510d8c9dba5560a2d537763566cf40nd directives later on. Arguments are passed to the map via the
fe64b2ba25510d8c9dba5560a2d537763566cf40nd following syntax:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p class="indent">
9bcfc3697a91b5215893a7d0206865b13fc72148nd <strong>
9bcfc3697a91b5215893a7d0206865b13fc72148nd <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
1f1b6bf13313fdd14a45e52e553d3ff28689b717coar <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton </strong>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton </p>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>When such a construct occurs, the map <em>MapName</em> is
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton consulted and the key <em>LookupKey</em> is looked-up. If the
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton key is found, the map-function construct is substituted by
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <em>SubstValue</em>. If the key is not found then it is
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton substituted by <em>DefaultValue</em> or by the empty string
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton if no <em>DefaultValue</em> was specified.</p>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>For example, you might define a
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <code class="directive">RewriteMap</code> as:</p>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <div class="example"><p><code>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton RewriteMap examplemap txt:/path/to/file/map.txt
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton </code></p></div>
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar <p>You would then be able to use this map in a
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <code class="directive">RewriteRule</code> as follows:</p>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<div class="example"><p><code>
20f499565e77defe9dab24dd85c02f38a1175855nd RewriteRule ^/ex/(.*) ${examplemap:$1}
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton</code></p></div>
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<p>A default value can be specified in the event that nothing is found
a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonin the map:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="example"><p><code>
fe64b2ba25510d8c9dba5560a2d537763566cf40ndRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
75241911a05371c31eb43e91cd40645a905408cccolm</code></p></div>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<div class="note"><h3>Per-directory and .htaccess context</h3>
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh<p>
3ffe84681ed8add175b7b33f1985d9db941eccaftrawickThe <code>RewriteMap</code> directive may not be used in
fe64b2ba25510d8c9dba5560a2d537763566cf40nd&lt;Directory&gt; sections or <code>.htaccess</code> files. You must
fe64b2ba25510d8c9dba5560a2d537763566cf40nddeclare the map in server or virtualhost context. You may use the map,
fe64b2ba25510d8c9dba5560a2d537763566cf40ndonce created, in your <code>RewriteRule</code> and
75241911a05371c31eb43e91cd40645a905408cccolm<code>RewriteCond</code> directives in those scopes. You just can't
d8e53ebbaf8cdc872236a202b5a9fc9997348a34covener<strong>declare</strong> it in those scopes.
75241911a05371c31eb43e91cd40645a905408cccolm</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive</div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>The sections that follow describe the various <em>MapType</em>s that
06ba4a61654b3763ad65f52283832ebf058fdf1cslivemay be used, and give examples of each.</p>
f2c4476994729750806eaa70d8b55fa2b3eba25brbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh<div class="section">
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh
bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh
20f499565e77defe9dab24dd85c02f38a1175855nd <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
e487d6c09669296f94a5190cc34586a98e624a00nd plain-text mapping file, containing space-separated key/value pair
f2c4476994729750806eaa70d8b55fa2b3eba25brbowen per line. Optionally, a line may be contain a comment, starting with
fe64b2ba25510d8c9dba5560a2d537763566cf40nd a '#' character.</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd
fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p>For example, the following might be valid entries in a map
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd file.</p>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd
660c7c6d7e175238807ffc144c0f8e746bf2cfb0minfrin <p class="indent">
7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd # Comment line<br />
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
727872d18412fc021f03969b8641810d8896820bhumbedooh <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
0d0ba3a410038e179b695446bb149cce6264e0abnd </p>
727872d18412fc021f03969b8641810d8896820bhumbedooh
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh <p>When the RewriteMap is invoked the argument is looked for in the
0d0ba3a410038e179b695446bb149cce6264e0abnd first argument of a line, and, if found, the substitution value is
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh returned.</p>
727872d18412fc021f03969b8641810d8896820bhumbedooh
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>For example, we might use a mapfile to translate product names to
0d0ba3a410038e179b695446bb149cce6264e0abnd product IDs for easier-to-remember URLs, using the following
0d0ba3a410038e179b695446bb149cce6264e0abnd recipe:</p>
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh
0d0ba3a410038e179b695446bb149cce6264e0abnd <div class="example"><h3>Product to ID configuration</h3><p><code>
0d0ba3a410038e179b695446bb149cce6264e0abnd RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
0d0ba3a410038e179b695446bb149cce6264e0abnd RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
727872d18412fc021f03969b8641810d8896820bhumbedooh </code></p></div>
0d0ba3a410038e179b695446bb149cce6264e0abnd
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>We assume here that the <code>prods.php</code> script knows what
30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh to do when it received an argument of <code>id=NOTFOUND</code> when
205f749042ed530040a4f0080dbcb47ceae8a374rjung a product is not found in the lookup map.</p>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen
0d0ba3a410038e179b695446bb149cce6264e0abnd <p>The file <code>/etc/apache2/productmap.txt</code> then contains
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd the following:</p>
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <div class="example"><h3>Product to ID map</h3><p><code>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd##<br />
## productmap.txt - Product to ID map file<br />
##<br />
<br />
television 993<br />
stereo 198<br />
fishingrod 043<br />
basketball 418<br />
telephone 328
</code></p></div>
<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>
<div class="note"><h3>Note: .htaccess files</h3>
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:
<div class="example"><p><code>
RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
</code></p></div>
</div>
<div class="note"><h3>Cached lookups</h3>
<p>
The looked-up keys are cached by httpd until the <code>mtime</code>
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
</p>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
<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 servers, via a reverse-proxy. Images are sent
to one of the servers in the 'static' pool, while everything
else is sent to one of the 'dynamic' pool.</p>
<div class="example"><h3>Rewrite map file</h3><p><code>
##<br />
## map.txt -- rewriting map<br />
##<br />
<br />
static www1|www2|www3|www4<br />
dynamic www5|www6
</code></p></div>
<div class="example"><h3>Configuration directives</h3><p><code>
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]
</code></p></div>
<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>
<div class="example"><p><code>
static www1|www1|www2|www3|www4
</code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
<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>
<div class="example"><p><code>
RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
</code></p></div>
<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>
<div class="example"><p><code>
$ httxt2dbm -i mapfile.txt -o mapfile.map
</code></p></div>
<p>You can then reference the resulting file in your
<code>RewriteMap</code> directive:</p>
<div class="example"><p><code>
RewriteMap mapname dbm:/etc/apache/mapfile.map
</code></p></div>
<div class="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>
</div>
<div class="note"><h3>Cached lookups</h3>
<p>
The looked-up keys are cached by httpd until the <code>mtime</code>
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
</p>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="int" id="int">int: Internal Function</a></h2>
<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>
<div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
RewriteMap lc int:tolower<br />
RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
</code></p></div>
<div class="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
<code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
</p>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
<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 <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> 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
<code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p>
<p>A simple example is shown here which will replace all dashes with
underscores in a request URI.</p>
<div class="example"><h3>Rewrite configuration</h3><p><code>
RewriteMap d2u prg:/www/bin/dash2under.pl<br />
RewriteRule - ${d2u:%{REQUEST_URI}}
</code></p></div>
<div class="example"><h3>dash2under.pl</h3><p><code>
#!/usr/bin/perl<br />
$| = 1; # Turn off I/O buffering<br />
while (&lt;STDIN&gt;) {<br />
<span class="indent">
s/-/_/g; # Replace dashes with underscores<br />
print $_;<br />
</span>
}<br />
</code></p></div>
<div class="note"><h3>Caution!</h3>
<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>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
<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><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> 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>
<div class="example"><h3>Example</h3><p><code>
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
</code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="summary" id="summary">Summary</a></h2>
<p>The <code class="directive">RewriteMap</code> directive can occur more than
once. For each mapping-function use one
<code class="directive">RewriteMap</code> 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>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>
</body></html>