rewritemap.html.en revision 07dc96d063d49299da433f84b5c5681da9bbdf68
530eba85dbd41b8a0fa5255d3648d1440199a661slive<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
e942c741056732f50da2074b36fe59805d370650slive<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd This file is generated from xml source: DO NOT EDIT
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<title>Using RewriteMap - Apache HTTP Server</title>
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<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" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<script src="/style/scripts/prettify.js" type="text/javascript">
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<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>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
530eba85dbd41b8a0fa5255d3648d1440199a661slive <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernathe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaand provides examples of each of the various <code>RewriteMap</code> types.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <div class="warning">Note that many of these examples won't work unchanged in your
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaparticular server configuration, so it's important that you understand
158222078a98fb13cddf2793b42f7eb8eafe51aerjungthem, rather than merely cutting and pasting the examples into your
158222078a98fb13cddf2793b42f7eb8eafe51aerjungconfiguration.</div>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
31127de9133204b2f09f6226250592ed93b61023rbowen<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe</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>
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<h2><a name="introduction" id="introduction">Introduction</a></h2>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier defines an external function which can be called in the context of
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier perform rewriting that is too complicated, or too specialized to be
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier performed just by regular expressions. The source of this lookup can
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier be any of the types listed in the sections below, and enumerated in
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
2aa51ed61adb484602e94de3d2214ec267aecedbigalic documentation.</p>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <p>The syntax of the <code>RewriteMap</code> directive is as
2aa51ed61adb484602e94de3d2214ec267aecedbigalic follows:</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<pre class="prettyprint lang-config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></pre>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor arbitray name that you assign to the map, and which you will use in
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna directives later on. Arguments are passed to the map via the
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna following syntax:</p>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>When such a construct occurs, the map <em>MapName</em> is
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor consulted and the key <em>LookupKey</em> is looked-up. If the
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna key is found, the map-function construct is substituted by
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <em>SubstValue</em>. If the key is not found then it is
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna substituted by <em>DefaultValue</em> or by the empty string
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <p>For example, you can define a
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <pre class="prettyprint lang-config">RewriteMap examplemap txt:/path/to/file/map.txt</pre>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe <p>You would then be able to use this map in a
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe <code class="directive">RewriteRule</code> as follows:</p>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1}</pre>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<p>A default value can be specified in the event that nothing is found
5ae609a8a09239d20f48a4a95c4f21b713995babwrowein the map:</p>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</pre>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<div class="note"><h3>Per-directory and .htaccess context</h3>
5ae609a8a09239d20f48a4a95c4f21b713995babwroweThe <code>RewriteMap</code> directive may not be used in
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<Directory> sections or <code>.htaccess</code> files. You must
031bbbc0d1189b07330e38d0c126820a9ab7795egryzordeclare the map in server or virtualhost context. You may use the map,
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<code>RewriteCond</code> directives in those scopes. You just can't
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<p>The sections that follow describe the various <em>MapType</em>s that
313bb560bc5c323cfd40c9cad7335b4b8e060aedkessmay be used, and give examples of each.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<h2><a name="int" id="int">int: Internal Function</a></h2>
18b4b0fd6056093002ddef488636bf5ebe415ef0erikabele <p>When a MapType of <code>int</code> is used, the MapSource is one
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive of the available internal RewriteMap functions. Module authors can provide
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive additional internal functions by registering them with the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The functions that are provided by default are:
fb77c505254b6e9c925e23e734463e87574f8f40kess Converts the key to all upper case.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Converts the key to all lower case.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Translates special characters in the key to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive hex-encodings.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess Translates hex-encodings in the key back to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive special characters.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess To use one of these functions, create a <code>RewriteMap</code> referencing
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the int function, and then use that in your <code>RewriteRule</code>:
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteMap lc int:tolower
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Please note that the example offered here is for
fb77c505254b6e9c925e23e734463e87574f8f40kess illustration purposes only, and is not a recommendation. If you want
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess to make URLs case-insensitive, consider using
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
fb77c505254b6e9c925e23e734463e87574f8f40kess plain-text mapping file, containing space-separated key/value pair
fb77c505254b6e9c925e23e734463e87574f8f40kess per line. Optionally, a line may be contain a comment, starting with
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a '#' character.</p>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <p>A valid text rewrite map file will have the following syntax:</p>
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh # Comment line<br />
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When the RewriteMap is invoked the argument is looked for in the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive first argument of a line, and, if found, the substitution value is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive returned.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For example, we can use a mapfile to translate product names to
003f0c9fda6664daf5092a0e42f65ede20098153slive product IDs for easier-to-remember URLs, using the following
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd recipe:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
003f0c9fda6664daf5092a0e42f65ede20098153slive <p>We assume here that the <code>prods.php</code> script knows what
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess to do when it received an argument of <code>id=NOTFOUND</code> when
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess a product is not found in the lookup map.</p>
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh <p>The file <code>/etc/apache2/productmap.txt</code> then contains
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the following:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <div class="example"><h3>Product to ID map</h3><p><code>
2aa51ed61adb484602e94de3d2214ec267aecedbigalictelevision 993<br />
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedoohstereo 198<br />
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedoohfishingrod 043<br />
2aa51ed61adb484602e94de3d2214ec267aecedbigalicbasketball 418<br />
2aa51ed61adb484602e94de3d2214ec267aecedbigalictelephone 328
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Thus, when <code>http://example.com/product/television</code> is
1a3f62ca37273a15a06bb94a61d3c6fcf4bf38c9rbowen requested, the <code>RewriteRule</code> is applied, and the request
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive is internally mapped to <code>/prods.php?id=993</code>.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The example given is crafted to be used in server or virtualhost
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding scope. If you're planning to use this in a <code>.htaccess</code>
684f2a9a422185adda0692a1203c5ad6687fc5c5nd file, you'll need to remove the leading slash from the rewrite
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd pattern in order for it to match anything:
530eba85dbd41b8a0fa5255d3648d1440199a661slive <pre class="prettyprint lang-config">RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]</pre>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The looked-up keys are cached by httpd until the <code>mtime</code>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding (modified time) of the mapfile changes, or the httpd server is
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding restarted. This ensures better performance on maps that are called
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding by many requests.
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <p>When a MapType of <code>rnd</code> is used, the MapSource is a
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding filesystem path to a plain-text mapping file, each line of which
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive contains a key, and one or more values separated by <code>|</code>.
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh One of these values will be chosen at random if the key is
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding matched.</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <p>For example, you can use the following map
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding file and directives to provide a random load balancing between
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding several back-end servers, via a reverse-proxy. Images are sent
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding to one of the servers in the 'static' pool, while everything
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding else is sent to one of the 'dynamic' pool.</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <div class="example"><h3>Rewrite map file</h3><p><code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivestatic www1|www2|www3|www4<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivedynamic www5|www6
77ead9e0262e4f08ec336d1a65b2edef7705c839ndRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
77ead9e0262e4f08ec336d1a65b2edef7705c839ndRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <p>So, when an image is requested and the first of these rules is
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>static</code> in the map file, which returns one of the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd specified hostnames at random, which is then used in the
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier <p>If you wanted to have one of the servers more likely to be chosen
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier (for example, if one of the server has more memory than the others,
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier and so can handle more requests) simply list it more times in the
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier map file.</p>
3770ed746d69c7a4111cba9966169bd5d7a509a6poirierstatic www1|www1|www2|www3|www4
77ead9e0262e4f08ec336d1a65b2edef7705c839nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier <p>When a MapType of <code>dbm</code> is used, the MapSource is a
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier filesystem path to a DBM database file containing key/value pairs to
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier be used in the mapping. This works exactly the same way as the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd <code>txt</code> map, but is much faster, because a DBM is indexed,
77ead9e0262e4f08ec336d1a65b2edef7705c839nd whereas a text file is not. This allows more rapid access to the
77ead9e0262e4f08ec336d1a65b2edef7705c839nd desired key.</p>
4ea161d94782fa56f4b36d496f35ff8577c43065covener <p>The type can be sdbm, gdbm, ndbm or db.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive provided with Apache HTTP Server, as it will use the correct DBM library,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive matching the one that was used when httpd itself was built.</p>
fb77c505254b6e9c925e23e734463e87574f8f40kess <p>To create a dbm file, first create a text map file as described
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd<p>You can then reference the resulting file in your
113961f0559eb026ea0d379cb7350f82bc09d710druggeri<p>Note that with some dbm types, more than one file is generated, with
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivea common base name. For example, you may have two files named
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivenormal, and you need only use the base name <code>mapfile.map</code> in
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveThe looked-up keys are cached by httpd until the <code>mtime</code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive(modified time) of the mapfile changes, or the httpd server is
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliverestarted. This ensures better performance on maps that are called
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveby many requests.
0834a50e694f91f4bf20ddf030fd0812e65cafc7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
9ed9eaf871c58d281af02e76125ceadb5060afa5nd<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
9cd3b05d7b70f07a742bbaf548fa4fa2bdbe5ce6noodl <p>When a MapType of <code>prg</code> is used, the MapSource is a
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz filesystem path to an executable program which will providing the
9cd3b05d7b70f07a742bbaf548fa4fa2bdbe5ce6noodl mapping behavior. This can be a compiled binary file, or a program
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive in an interpreted language such as Perl or Python.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>This program is started once, when the Apache HTTP Server is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive started, and then communicates with the rewriting engine via
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding function lookup, it expects one argument via <code>STDIN</code>, and
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding should return one new-line terminated response string on
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <code>STDOUT</code>. If there is no corresponding lookup value, the
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding map program should return the four-character string
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <p>External rewriting programs are not started if they're defined in
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <p>This feature utilizes the <code>rewrite-map</code> mutex,
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem which is required for reliable communication with the program.
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem The mutex mechanism and lock file can be configured with the
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <p>A simple example is shown here which will replace all dashes with
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem underscores in a request URI.</p>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluemRewriteRule - ${d2u:%{REQUEST_URI}}
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem $| = 1; # Turn off I/O buffering
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem while (<STDIN>) {
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem s/-/_/g; # Replace dashes with underscores
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li>Keep your rewrite map program as simple as possible. If the program
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivehangs, it will cause httpd to wait indefinitely for a response from the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivemap, which will, in turn, cause httpd to stop responding to
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliverequests.</li>
06cec0eb90affb7f85de964d1822fddc77553c32humbedooh<li>Be sure to turn off buffering in your program. In Perl this is done
06cec0eb90affb7f85de964d1822fddc77553c32humbedoohby the second line in the example script: <code>$| = 1;</code> This will
0834a50e694f91f4bf20ddf030fd0812e65cafc7rbowenof course vary in other languages. Buffered I/O will cause httpd to wait
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivefor the output, and so it will hang.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li>Remember that there is only one copy of the program, started at
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveserver startup. All requests will need to go through this one bottleneck.
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveThis can cause significant slowdowns if many requests must go through
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivethis process, or if the script itself is very slow.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
8cb1b3a3753304d51919865f588cbe19cbd0182arbowen<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
83f7a8612f5d7899d2d84d6f3f83f1ca4f86cc56rbowen used, the MapSource is a SQL SELECT statement that takes a single
83f7a8612f5d7899d2d84d6f3f83f1ca4f86cc56rbowen argument and returns a single value.</p>
eb73941bd697cd7e8226ceaf04183ade6c66934dniq <p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
e67969aeb443b18bbb3837690c4010c3f1961842jim the right database for this statement to be executed.</p>
eb73941bd697cd7e8226ceaf04183ade6c66934dniq <p>There are two forms of this MapType.
eb73941bd697cd7e8226ceaf04183ade6c66934dniq Using a MapType of <code>dbd</code> causes the query to be
eb73941bd697cd7e8226ceaf04183ade6c66934dniq executed with each map request, while using <code>fastdbd</code>
eb73941bd697cd7e8226ceaf04183ade6c66934dniq caches the database lookups internally. So, while
eb73941bd697cd7e8226ceaf04183ade6c66934dniq <code>fastdbd</code> is more efficient, and therefore faster, it
eb73941bd697cd7e8226ceaf04183ade6c66934dniq won't pick up on changes to the database until the server is
eb73941bd697cd7e8226ceaf04183ade6c66934dniq restarted.</p>
eb73941bd697cd7e8226ceaf04183ade6c66934dniq <p>If a query returns more than one row, a random row from
eb73941bd697cd7e8226ceaf04183ade6c66934dniqthe result set is used.</p>
eb73941bd697cd7e8226ceaf04183ade6c66934dniq <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
eb73941bd697cd7e8226ceaf04183ade6c66934dniqRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
eb73941bd697cd7e8226ceaf04183ade6c66934dniq </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
beefdf2539f2cd75fd45f5d560cbb26783ff9db1jim <p>The <code class="directive">RewriteMap</code> directive can occur more than
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive once. For each mapping-function use one
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code class="directive">RewriteMap</code> directive to declare its rewriting
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive mapfile.</p>
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna <p>While you cannot <strong>declare</strong> a map in
103a93c625bcde1a6a7a5155b64dcda36f612180pquerna per-directory context (<code>.htaccess</code> files or
f23fb63b05f89f47d7a3099491f2c68dcce432e9kess <Directory> blocks) it is possible to
9970ad80054f477c708284a0d030a5bd26e412a9covener <strong>use</strong> this map in per-directory context. </p>
f7acc4b00a8bf92fea10fce6ac09aa57eafec0ecjim<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
9970ad80054f477c708284a0d030a5bd26e412a9covener</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>
9970ad80054f477c708284a0d030a5bd26e412a9covener<script type="text/javascript"><!--//--><![CDATA[//><!--
9970ad80054f477c708284a0d030a5bd26e412a9covenervar comments_shortname = 'httpd';
9970ad80054f477c708284a0d030a5bd26e412a9covenervar comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/rewritemap.html';
9970ad80054f477c708284a0d030a5bd26e412a9covener(function(w, d) {
d8655d95f4c9f281adc457de9ef702b46b003153rbowen if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
d8655d95f4c9f281adc457de9ef702b46b003153rbowen d.write('<div id="comments_thread"><\/div>');
08a6627a8cb9a9c85392cd0d8680c112a7f857cetrawick var s = d.createElement('script');
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd})(window, document);
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd<p class="apache">Copyright 2014 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>
da637bcae7b6e150470e701af29da5604a34a17erbowen<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[//><!--
da637bcae7b6e150470e701af29da5604a34a17erbowenif (typeof(prettyPrint) !== 'undefined') {
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor prettyPrint();