rewritemap.html.en revision f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654
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
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" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/images/favicon.ico" rel="shortcut icon" /></head>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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.3</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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<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>
53abc235688d883cfa15cdfec354ba03128f357arbowen</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>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenRewriteMap <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
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>For example, you might define a
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>You would then be able to use this map in a
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenin the map:</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenRewriteRule ^/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
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<p>The sections that follow describe the various <em>MapType</em>s that
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenmay be used, and give examples of each.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
2509f1cd3be884abbe4852e15b8da00bebaad5b1poirier <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 <p>For example, the following might be valid entries in a map
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 />
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 <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 <div class="example"><h3>Product to ID configuration</h3><p><code>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
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 <p>The file <code>/etc/apache2/productmap.txt</code> then contains
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen the following:</p>
353e838f5716b394f2f9bf38549e1550a5e73570rbowen <div class="example"><h3>Product to ID map</h3><p><code>
353e838f5716b394f2f9bf38549e1550a5e73570rbowentelevision 993<br />
353e838f5716b394f2f9bf38549e1550a5e73570rbowenstereo 198<br />
353e838f5716b394f2f9bf38549e1550a5e73570rbowenfishingrod 043<br />
353e838f5716b394f2f9bf38549e1550a5e73570rbowenbasketball 418<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelephone 328
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 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]
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen The looked-up keys are cached by httpd until the <code>mtime</code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen (modified time) of the mapfile changes, or the httpd server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen restarted. This ensures better performance on maps that are called
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen by many requests.
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
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 <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>
353e838f5716b394f2f9bf38549e1550a5e73570rbowen <div class="example"><h3>Rewrite map file</h3><p><code>
353e838f5716b394f2f9bf38549e1550a5e73570rbowenstatic www1|www2|www3|www4<br />
0a3142725875ea286597e083547d34d98f8c1f2drbowendynamic www5|www6
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <div class="example"><h3>Configuration directives</h3><p><code>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>So, when an image is requested and the first of these rules is
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 <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>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowenstatic www1|www1|www2|www3|www4
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>When a MapType of <code>dbm</code> is used, the MapSource is a
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen filesystem path to a DBM database file containing key/value pairs to
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen be used in the mapping. This works exactly the same way as the
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <code>txt</code> map, but is much faster, because a DBM is indexed,
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen whereas a text file is not. This allows more rapid access to the
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen desired key.</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>You may optionally specify a particular dbm type:</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>The type can be sdbm, gdbm, ndbm or db.
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen provided with Apache HTTP Server, as it will use the correct DBM library,
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen matching the one that was used when httpd itself was built.</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>To create a dbm file, first create a text map file as described
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<p>You can then reference the resulting file in your
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<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
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThe looked-up keys are cached by httpd until the <code>mtime</code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen(modified time) of the mapfile changes, or the httpd server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenrestarted. This ensures better performance on maps that are called
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenby many requests.
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="int" id="int">int: Internal Function</a></h2>
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <p>When a MapType of <code>int</code> is used, the MapSource is one
9a58dc6a2b26ec128b1270cf48810e705f1a90dbsf of the available internal RewriteMap functions. Module authors can provide
9fa69be7454a9c2f1ef63321fd04eae825e48d79covener additional internal functions by registering them with the
cb2bc248359cade6518cf6c68394dc6865ba992ccovener The functions that are provided by default are:
0a3142725875ea286597e083547d34d98f8c1f2drbowen Converts the key to all upper case.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Converts the key to all lower case.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates special characters in the key to
0a3142725875ea286597e083547d34d98f8c1f2drbowen hex-encodings.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates hex-encodings in the key back to
0a3142725875ea286597e083547d34d98f8c1f2drbowen special characters.</li>
5c5ef751538ad31a6cef69f814996fe7453e383drbowen To use one of these functions, create a <code>RewriteMap</code> referencing
5c5ef751538ad31a6cef69f814996fe7453e383drbowen the int function, and then use that in your <code>RewriteRule</code>:
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
5c5ef751538ad31a6cef69f814996fe7453e383drbowen RewriteMap lc int:tolower<br />
8559a67073808d84d85bb5dd552d4247caafe709sf RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <p>Please note that the example offered here is for
5c5ef751538ad31a6cef69f814996fe7453e383drbowen illustration purposes only, and is not a recommendation. If you want
5c5ef751538ad31a6cef69f814996fe7453e383drbowen to make URLs case-insensitive, consider using
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<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
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen should return one new-line terminated response string on
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>STDOUT</code>. If there is no corresponding lookup value, the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen map program should return the four-character string
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <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>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>A simple example is shown here which will replace all dashes with
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen underscores in a request URI.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <div class="example"><h3>Rewrite configuration</h3><p><code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen RewriteRule - ${d2u:%{REQUEST_URI}}
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen $| = 1; # Turn off I/O buffering<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen 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
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenthis 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>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<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>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen caches the database lookups internally. So, while
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>fastdbd</code> is more efficient, and therefore faster, it
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen won't pick up on changes to the database until the server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen restarted.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>If a query returns more than one row, a random row from
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenthe result set is used.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <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>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>While you cannot <strong>declare</strong> a map in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen per-directory context (<code>.htaccess</code> files or
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <Directory> blocks) it is possible to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <strong>use</strong> this map in per-directory context. </p>
f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
9c1260efa52c82c2a58e5b5f20cd6902563d95f5rbowen<p class="apache">Copyright 2011 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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>