0a3142725875ea286597e083547d34d98f8c1f2drbowen<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
fd9abdda70912b99b24e3bf1a38f26fde908a74cnd<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0a3142725875ea286597e083547d34d98f8c1f2drbowen This file is generated from xml source: DO NOT EDIT
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
96ad5d81ee4a2cc66a4ae19893efc8aa6d06fae7jailletc<title>Using RewriteMap - Apache HTTP Server Version 2.5</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.min.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/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/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="#int">int: Internal Function</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="#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><ul class="seealso"><li><a href="#comments_section">Comments</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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<pre class="prettyprint lang-config">RewriteMap <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 can define a
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap examplemap "txt:/path/to/file/map.txt"</pre>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>You would then be able to use this map in a
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code class="directive">RewriteRule</code> as follows:</p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteRule "^/ex/(.*)" "${examplemap:$1}"</pre>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<p>A default value can be specified in the event that nothing is found
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenin the map:</p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<pre class="prettyprint lang-config">RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"</pre>
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>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen<h2><a name="int" id="int">int: Internal Function</a></h2>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>When a MapType of <code>int</code> is used, the MapSource is one
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen of the available internal RewriteMap functions. Module authors can provide
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen additional internal functions by registering them with the
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen The functions that are provided by default are:
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen Converts the key to all upper case.</li>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen Converts the key to all lower case.</li>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen Translates special characters in the key to
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen hex-encodings.</li>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen Translates hex-encodings in the key back to
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen special characters.</li>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen To use one of these functions, create a <code>RewriteMap</code> referencing
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen the int function, and then use that in your <code>RewriteRule</code>:
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap lc "int:tolower"
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteRule "(.*?[A-Z]+.*)" "${lc:$1}" [R]</pre>
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <p>Please note that the example offered here is for
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen illustration purposes only, and is not a recommendation. If you want
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen to make URLs case-insensitive, consider using
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen <code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
418d2a426a2a3e6900e34bf727eeec7bed57656brbowen </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>
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen <p>A valid text rewrite map file will have the following syntax:</p>
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>
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen <p>For example, we can use a mapfile to translate product names to
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen product IDs for easier-to-remember URLs, using the following
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen recipe:</p>
95ab37c71e0d89443389909b290c98f8fc80ec5ehumbedooh<p><strong>Product to ID configuration</strong></p>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap product2id "txt:/etc/apache2/productmap.txt"
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]</pre>
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:
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]</pre>
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>
4617de5c96f79a1b2a6ac678963e4ce14cfb4215rbowen <p>For example, you can use the following map
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen file and directives to provide a random load balancing between
4bf04ac5fe6a2ae518bd0d8d463f069253d46c0arbowen several back-end servers, 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
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap servers "rnd:/path/to/file/map.txt"
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]</pre>
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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"</pre>
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
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<pre class="prettyprint lang-config">RewriteMap mapname "dbm:/etc/apache/mapfile.map"</pre>
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>
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
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen <p>By default, external rewriting programs are run as the
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen user:group who started httpd. This can be changed on UNIX systems
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen by passing user name and group name as third argument to
694390dc2444235cbd378d1c2711d5b698cf95ccrbowen <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> in the
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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar <pre class="prettyprint lang-config">RewriteMap d2u "prg:/www/bin/dash2under.programlisting" apache:apache<br />
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarRewriteRule "-" "${d2u:%{REQUEST_URI}}"</pre>
b4cb09c5f4fb645b71112098e46a643b6a9731a6humbedooh $| = 1; # Turn off I/O buffering
b4cb09c5f4fb645b71112098e46a643b6a9731a6humbedooh while (<STDIN>) {
b4cb09c5f4fb645b71112098e46a643b6a9731a6humbedooh s/-/_/g; # Replace dashes with underscores
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>
4aa603e6448b99f9371397d439795c91a93637eand <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"</pre>
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>
ed62c84ee0911cfebbd8da319ac00757b555707chumbedooh</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
ed62c84ee0911cfebbd8da319ac00757b555707chumbedoohvar comments_shortname = 'httpd';
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohvar comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/rewritemap.html';
0d0ba3a410038e179b695446bb149cce6264e0abnd(function(w, d) {
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
ed62c84ee0911cfebbd8da319ac00757b555707chumbedooh d.write('<div id="comments_thread"><\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd var s = d.createElement('script');
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
0d0ba3a410038e179b695446bb149cce6264e0abnd (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
ed62c84ee0911cfebbd8da319ac00757b555707chumbedooh d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
0d0ba3a410038e179b695446bb149cce6264e0abnd})(window, document);
205f749042ed530040a4f0080dbcb47ceae8a374rjung<p class="apache">Copyright 2015 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>
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
0d0ba3a410038e179b695446bb149cce6264e0abndif (typeof(prettyPrint) !== 'undefined') {
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd prettyPrint();