rewritemap.html.en revision d29d9ab4614ff992b0e8de6e2b88d52b6f1f153e
0a3142725875ea286597e083547d34d98f8c1f2drbowen<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
0a3142725875ea286597e083547d34d98f8c1f2drbowen<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0a3142725875ea286597e083547d34d98f8c1f2drbowen This file is generated from xml source: DO NOT EDIT
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Using RewriteMap - Apache HTTP Server</title>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" />
2e545ce2450a9953665f701bb05350f0d3f26275nd<script src="/style/scripts/prettify.js" type="text/javascript">
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/images/favicon.ico" rel="shortcut icon" /></head>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
3f08db06526d6901aa08c110b5bc7dde6bc39905nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.5</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
0a3142725875ea286597e083547d34d98f8c1f2drbowenthe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
0a3142725875ea286597e083547d34d98f8c1f2drbowenand provides examples of each of the various <code>RewriteMap</code> types.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <div class="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.</div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
3cfb051391f3d6aa28a25ca3feb81e841242f9d5humbedooh</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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<h2><a name="introduction" id="introduction">Introduction</a></h2>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen defines an external function which can be called in the context of
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> 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 <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen documentation.</p>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <p>The syntax of the <code>RewriteMap</code> directive is as
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen follows:</p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
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 <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>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <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
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen <p>For example, you might define a
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>You would then be able to use this map in a
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <code class="directive">RewriteRule</code> as follows:</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^/ex/(.*) ${examplemap:$1}
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<p>A default value can be specified in the event that nothing is found
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarin the map:</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<div class="note"><h3>Per-directory and .htaccess context</h3>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThe <code>RewriteMap</code> directive may not be used in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<Directory> sections or <code>.htaccess</code> files. You must
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowendeclare the map in server or virtualhost context. You may use the map,
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<code>RewriteCond</code> directives in those scopes. You just can't
0a3142725875ea286597e083547d34d98f8c1f2drbowen<p>The sections that follow describe the various <em>MapType</em>s that
418d2a426a2a3e6900e34bf727eeec7bed57656brbowenmay be used, and give examples of each.</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen plain-text mapping file, containing space-separated key/value pair
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen per line. Optionally, a line may be contain a comment, starting with
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen a '#' character.</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>For example, the following might be valid entries in a map
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen # Comment line<br />
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>When the RewriteMap is invoked the argument is looked for in the
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen first argument of a line, and, if found, the substitution value is
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen returned.</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>For example, we might use a mapfile to translate product names to
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen product IDs for easier-to-remember URLs, using the following
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen recipe:</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <div class="example"><h3>Product to ID configuration</h3><p><code>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>We assume here that the <code>prods.php</code> script knows what
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen to do when it received an argument of <code>id=NOTFOUND</code> when
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen a product is not found in the lookup map.</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>The file <code>/etc/apache2/productmap.txt</code> then contains
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen the following:</p>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <div class="example"><h3>Product to ID map</h3><p><code>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelevision 993<br />
2509f1cd3be884abbe4852e15b8da00bebaad5b1poirierstereo 198<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenfishingrod 043<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenbasketball 418<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelephone 328
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>Thus, when <code>http://example.com/product/television</code> is
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen requested, the <code>RewriteRule</code> is applied, and the request
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen is internally mapped to <code>/prods.php?id=993</code>.</p>
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen 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:
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar The looked-up keys are cached by httpd until the <code>mtime</code>
488228a03efe42d9f0b03334a4753ce79a6dc5cchumbedooh (modified time) of the mapfile changes, or the httpd server is
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen restarted. This ensures better performance on maps that are called
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen by many requests.
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
353e838f5716b394f2f9bf38549e1550a5e73570rbowen <p>When a MapType of <code>rnd</code> is used, the MapSource is a
353e838f5716b394f2f9bf38549e1550a5e73570rbowen filesystem path to a plain-text mapping file, each line of which
353e838f5716b394f2f9bf38549e1550a5e73570rbowen contains a key, and one or more values separated by <code>|</code>.
353e838f5716b394f2f9bf38549e1550a5e73570rbowen One of these values will be chosen at random if the key is
353e838f5716b394f2f9bf38549e1550a5e73570rbowen matched.</p>
353e838f5716b394f2f9bf38549e1550a5e73570rbowen <p>For example, you might use the following map
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen file and directives to provide a random load balancing between
353e838f5716b394f2f9bf38549e1550a5e73570rbowen several back-end servers, via a reverse-proxy. Images are sent
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen to one of the servers in the 'static' pool, while everything
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen else is sent to one of the 'dynamic' pool.</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <div class="example"><h3>Rewrite map file</h3><p><code>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenstatic www1|www2|www3|www4<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowendynamic www5|www6
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <div class="example"><h3>Configuration directives</h3><p><code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>So, when an image is requested and the first of these rules is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>static</code> in the map file, which returns one of the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen specified hostnames at random, which is then used in the
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>If you wanted to have one of the servers more likely to be chosen
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen (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>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowenstatic www1|www1|www2|www3|www4
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
4bf04ac5fe6a2ae518bd0d8d463f069253d46c0arbowen<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>When a MapType of <code>dbm</code> is used, the MapSource is a
353e838f5716b394f2f9bf38549e1550a5e73570rbowen filesystem path to a DBM database file containing key/value pairs to
353e838f5716b394f2f9bf38549e1550a5e73570rbowen be used in the mapping. This works exactly the same way as the
353e838f5716b394f2f9bf38549e1550a5e73570rbowen <code>txt</code> map, but is much faster, because a DBM is indexed,
353e838f5716b394f2f9bf38549e1550a5e73570rbowen whereas a text file is not. This allows more rapid access to the
353e838f5716b394f2f9bf38549e1550a5e73570rbowen desired key.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>You may optionally specify a particular dbm type:</p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <p>The type can be sdbm, gdbm, ndbm or db.
488228a03efe42d9f0b03334a4753ce79a6dc5cchumbedooh However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen provided with Apache HTTP Server, as it will use the correct DBM library,
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen matching the one that was used when httpd itself was built.</p>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>To create a dbm file, first create a text map file as described
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen<p>You can then reference the resulting file in your
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<p>Note that with some dbm types, more than one file is generated, with
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowena common base name. For example, you may have two files named
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowennormal, and you need only use the base name <code>mapfile.map</code> in
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowenThe looked-up keys are cached by httpd until the <code>mtime</code>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen(modified time) of the mapfile changes, or the httpd server is
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarrestarted. This ensures better performance on maps that are called
488228a03efe42d9f0b03334a4753ce79a6dc5cchumbedoohby many requests.
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<h2><a name="int" id="int">int: Internal Function</a></h2>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>When a MapType of <code>int</code> is used, the MapSource is one
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen of the available internal RewriteMap functions. Module authors can provide
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen additional internal functions by registering them with the
0a3142725875ea286597e083547d34d98f8c1f2drbowen The functions that are provided by default are:
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar Converts the key to all upper case.</li>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen Converts the key to all lower case.</li>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen Translates special characters in the key to
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen hex-encodings.</li>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen Translates hex-encodings in the key back to
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen special characters.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen To use one of these functions, create a <code>RewriteMap</code> referencing
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen the int function, and then use that in your <code>RewriteRule</code>:
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen RewriteMap lc int:tolower<br />
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <p>Please note that the example offered here is for
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen illustration purposes only, and is not a recommendation. If you want
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen to make URLs case-insensitive, consider using
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>When a MapType of <code>prg</code> is used, the MapSource is a
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen filesystem path to an executable program which will providing the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen mapping behavior. This can be a compiled binary file, or a program
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen in an interpreted language such as Perl or Python.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>This program is started once, when the Apache HTTP Server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen started, and then communicates with the rewriting engine via
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen function lookup, it expects one argument via <code>STDIN</code>, and
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen should return one new-line terminated response string on
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen <code>STDOUT</code>. If there is no corresponding lookup value, the
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen map program should return the four-character string
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen <p>External rewriting programs are not started if they're defined in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>This feature utilizes the <code>rewrite-map</code> mutex,
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen which is required for reliable communication with the program.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen The mutex mechanism and lock file can be configured with the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p>
95ab37c71e0d89443389909b290c98f8fc80ec5ehumbedooh <p>A simple example is shown here which will replace all dashes with
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar underscores in a request URI.</p>
488228a03efe42d9f0b03334a4753ce79a6dc5cchumbedooh <div class="example"><h3>Rewrite configuration</h3><p><code>
488228a03efe42d9f0b03334a4753ce79a6dc5cchumbedooh RewriteRule - ${d2u:%{REQUEST_URI}}
b4cb09c5f4fb645b71112098e46a643b6a9731a6humbedooh <div class="example"><h3>dash2under.pl</h3><p><code>
b4cb09c5f4fb645b71112098e46a643b6a9731a6humbedooh $| = 1; # Turn off I/O buffering<br />
4aa603e6448b99f9371397d439795c91a93637eand while (<STDIN>) {<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen s/-/_/g; # Replace dashes with underscores<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen print $_;<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Keep your rewrite map program as simple as possible. If the program
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenhangs, it will cause httpd to wait indefinitely for a response from the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenmap, which will, in turn, cause httpd to stop responding to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenrequests.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Be sure to turn off buffering in your program. In Perl this is done
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenby the second line in the example script: <code>$| = 1;</code> This will
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenof course vary in other languages. Buffered I/O will cause httpd to wait
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenfor the output, and so it will hang.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Remember that there is only one copy of the program, started at
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenserver startup. All requests will need to go through this one bottleneck.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThis can cause significant slowdowns if many requests must go through
0a3142725875ea286597e083547d34d98f8c1f2drbowenthis process, or if the script itself is very slow.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen used, the MapSource is a SQL SELECT statement that takes a single
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen argument and returns a single value.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen the right database for this statement to be executed.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>There are two forms of this MapType.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen Using a MapType of <code>dbd</code> causes the query to be
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen executed with each map request, while using <code>fastdbd</code>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen caches the database lookups internally. So, while
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <code>fastdbd</code> is more efficient, and therefore faster, it
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen won't pick up on changes to the database until the server is
4aa603e6448b99f9371397d439795c91a93637eand restarted.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>If a query returns more than one row, a random row from
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenthe result set is used.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>The <code class="directive">RewriteMap</code> directive can occur more than
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen once. For each mapping-function use one
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code class="directive">RewriteMap</code> directive to declare its rewriting
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen mapfile.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>While you cannot <strong>declare</strong> a map in
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung per-directory context (<code>.htaccess</code> files or
ed62c84ee0911cfebbd8da319ac00757b555707chumbedooh <Directory> blocks) it is possible to
0d0ba3a410038e179b695446bb149cce6264e0abnd <strong>use</strong> this map in per-directory context. </p>
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
0d0ba3a410038e179b695446bb149cce6264e0abnd<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>
0d0ba3a410038e179b695446bb149cce6264e0abnd<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><script type="text/javascript">
0d0ba3a410038e179b695446bb149cce6264e0abnd if (prettyPrint) {
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh prettyPrint();