rewritemap.html.en revision cb2bc248359cade6518cf6c68394dc6865ba992c
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" />
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding<link href="/images/favicon.ico" rel="shortcut icon" /></head>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<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>
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.3</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivethe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
530eba85dbd41b8a0fa5255d3648d1440199a661sliveand 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
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernathem, rather than merely cutting and pasting the examples into your
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernaconfiguration.</div>
88d86cfadffe2275a3dfb67a4d7bdc018630b661rbowen<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna<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>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<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="#prg">prg: External Rewriting Program</a></li>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
e4e60c2f7ba8f12b687f588b89e413842e9f2d76igalic<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor</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 and tricks</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<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>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh defines an external function which can be called in the context of
2aa51ed61adb484602e94de3d2214ec267aecedbigalic <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <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
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
4e9f8c5414e5fe39b5393641533edca65f6e8b91poirier documentation.</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <p>The syntax of the <code>RewriteMap</code> directive is as
2aa51ed61adb484602e94de3d2214ec267aecedbigalic follows:</p>
2aa51ed61adb484602e94de3d2214ec267aecedbigalicRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor <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
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor following syntax:</p>
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna <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
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor <em>SubstValue</em>. If the key is not found then it is
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquerna substituted by <em>DefaultValue</em> or by the empty string
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe <p>For example, you might define a
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe <p>You would then be able to use this map in a
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe <code class="directive">RewriteRule</code> as follows:</p>
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe RewriteRule ^/ex/(.*) ${examplemap:$1}
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<p>A default value can be specified in the event that nothing is found
5ae609a8a09239d20f48a4a95c4f21b713995babwrowein the map:</p>
5ae609a8a09239d20f48a4a95c4f21b713995babwroweRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
5ae609a8a09239d20f48a4a95c4f21b713995babwrowe<div class="note"><h3>Per-directory and .htaccess context</h3>
5ae609a8a09239d20f48a4a95c4f21b713995babwroweThe <code>RewriteMap</code> directive may not be used in
031bbbc0d1189b07330e38d0c126820a9ab7795egryzor<Directory> sections or <code>.htaccess</code> files. You must
7e8f5c6496b3825b6b128e2aacc4b1b09d28553dpquernadeclare the map in server or virtualhost context. You may use the map,
abad96c7b1becfc55c29a2933d909aa0b37b0fe0humbedooh<code>RewriteCond</code> directives in those scopes. You just can't
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess<p>The sections that follow describe the various <em>MapType</em>s that
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivemay 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="txt" id="txt">txt: Plain text maps</a></h2>
88d86cfadffe2275a3dfb67a4d7bdc018630b661rbowen <p>When a MapType of <code>txt</code>is used, the MapSource is a filesystem path to a
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive plain-text mapping file, containing space-separated key/value pair
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive per line. Optionally, a line may be contain a comment, starting with
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a '#' character.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For example, the following might be valid entries in a map
fb77c505254b6e9c925e23e734463e87574f8f40kess # Comment line<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <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
fb77c505254b6e9c925e23e734463e87574f8f40kess returned.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For example, we might use a mapfile to translate product names to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive product IDs for easier-to-remember URLs, using the following
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive recipe:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <div class="example"><h3>Product to ID configuration</h3><p><code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
fb77c505254b6e9c925e23e734463e87574f8f40kess <p>We assume here that the <code>prods.php</code> script knows what
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to do when it received an argument of <code>id=NOTFOUND</code> when
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a product is not found in the lookup map.</p>
fb77c505254b6e9c925e23e734463e87574f8f40kess <p>The file <code>/etc/apache2/productmap.txt</code> then contains
fb77c505254b6e9c925e23e734463e87574f8f40kess the following:</p>
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess## productmap.txt - Product to ID map file
fb77c505254b6e9c925e23e734463e87574f8f40kesstelevision 993
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivefishingrod 043
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivebasketball 418
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivetelephone 328
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>Thus, when <code>http://example.com/product/television</code> is
fb77c505254b6e9c925e23e734463e87574f8f40kess requested, the <code>RewriteRule</code> is applied, and the request
fb77c505254b6e9c925e23e734463e87574f8f40kess is internally mapped to <code>/prods.php?id=993</code>.</p>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic The example given is crafted to be used in server or virtualhost
2aa51ed61adb484602e94de3d2214ec267aecedbigalic scope. If you're planning to use this in a <code>.htaccess</code>
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh file, you'll need to remove the leading slash from the rewrite
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh pattern in order for it to match anything:
2aa51ed61adb484602e94de3d2214ec267aecedbigalic RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The looked-up keys are cached by httpd until the <code>mtime</code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive (modified time) of the mapfile changes, or the httpd server is
003f0c9fda6664daf5092a0e42f65ede20098153slive restarted. This ensures better performance on maps that are called
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd by many requests.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess <p>When a MapType of <code>rnd</code> is used, the MapSource is a
6b64034fa2a644ba291c484c0c01c7df5b8d982ckess 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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive matched.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For example, you might use the following map
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive file and directives to provide a random load balancing between
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive several back-end server, via a reverse-proxy. Images are sent
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to one of the servers in the 'static' pool, while everything
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive else is sent to one of the 'dynamic' pool.</p>
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh <div class="example"><h3>Rewrite map file</h3><pre>
2aa51ed61adb484602e94de3d2214ec267aecedbigalic## map.txt -- rewriting map
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivestatic www1|www2|www3|www4
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivedynamic www5|www6
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <div class="example"><h3>Configuration directives</h3><p><code>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
684f2a9a422185adda0692a1203c5ad6687fc5c5nd RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>So, when an image is requested and the first of these rules is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>static</code> in the map file, which returns one of the
003f0c9fda6664daf5092a0e42f65ede20098153slive specified hostnames at random, which is then used in the
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <p>If you wanted to have one of the servers more likely to be chosen
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding (for example, if one of the server has more memory than the others,
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding and so can handle more requests) simply list it more times in the
684f2a9a422185adda0692a1203c5ad6687fc5c5nd map file.</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fieldingstatic www1|www1|www2|www3|www4
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
2e4a251ce928e74ed84fd089cdceaf5f6b5c53f2humbedooh <p>When a MapType of <code>dbm</code> is used, the MapSource is a
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding filesystem path to a DBM database file containing key/value pairs to
684f2a9a422185adda0692a1203c5ad6687fc5c5nd be used in the mapping. This works exactly the same way as the
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <code>txt</code> map, but is much faster, because a DBM is indexed,
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding whereas a text file is not. This allows more rapid access to the
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding desired key.</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <p>You may optionally specify a particular dbm type:</p>
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
843a03fe0b138a4c1f64cb90a014e9417ac30691fielding <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,
77ead9e0262e4f08ec336d1a65b2edef7705c839nd matching the one that was used when httpd itself was built.</p>
9583adab6bc4b3758e41963c905d9dad9f067131nd <p>To create a dbm file, first create a text map file as described
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<p>You can then reference the resulting file in your
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier<p>Note that with some dbm types, more than one file is generated, with
3770ed746d69c7a4111cba9966169bd5d7a509a6poiriera common base name. For example, you may have two files named
3770ed746d69c7a4111cba9966169bd5d7a509a6poirier<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
3770ed746d69c7a4111cba9966169bd5d7a509a6poiriernormal, and you need only use the base name <code>mapfile.map</code> in
77ead9e0262e4f08ec336d1a65b2edef7705c839ndThe looked-up keys are cached by httpd until the <code>mtime</code>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd(modified time) of the mapfile changes, or the httpd server is
77ead9e0262e4f08ec336d1a65b2edef7705c839ndrestarted. This ensures better performance on maps that are called
3770ed746d69c7a4111cba9966169bd5d7a509a6poirierby many requests.
77ead9e0262e4f08ec336d1a65b2edef7705c839nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
77ead9e0262e4f08ec336d1a65b2edef7705c839nd<h2><a name="int" id="int">int: Internal Function</a></h2>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>int</code> is used, the MapSource is one
003f0c9fda6664daf5092a0e42f65ede20098153slive of the available internal RewriteMap functions. Module authors can provide
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess additional internal functions by registring them with the
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd The functions that are provided by default are:
fb77c505254b6e9c925e23e734463e87574f8f40kess Converts the key to all upper case.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess Converts the key to all lower case.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Translates special characters in the key to
313bb560bc5c323cfd40c9cad7335b4b8e060aedkess hex-encodings.</li>
fb77c505254b6e9c925e23e734463e87574f8f40kess Translates hex-encodings in the key back to
b12b918ae6baf9c5762ed61b7393d0e2198378c0nd special characters.</li>
10673857794a4b3d9568ca2d983722a87ed352f1rbowen To use one of these functions, create a <code>RewriteMap</code> referencing
10673857794a4b3d9568ca2d983722a87ed352f1rbowen the int function, and then use that in your <code>RewriteRule</code>:
113961f0559eb026ea0d379cb7350f82bc09d710druggeri <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
113961f0559eb026ea0d379cb7350f82bc09d710druggeri RewriteMap lc int:tolower<br />
113961f0559eb026ea0d379cb7350f82bc09d710druggeri RewriteRule (.*[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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to make URLs case-insensitive, consider using
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <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="prg" id="prg">prg: External Rewriting Program</a></h2>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>prg</code> is used, the MapSource is a
0834a50e694f91f4bf20ddf030fd0812e65cafc7rbowen filesystem path to an executable program which will providing the
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz mapping behavior. This can be a compiled binary file, or a program
9ed9eaf871c58d281af02e76125ceadb5060afa5nd in an interpreted language such as Perl or Python.</p>
9cd3b05d7b70f07a742bbaf548fa4fa2bdbe5ce6noodl <p>This program is started once, when the Apache HTTP Server is
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz started, and then communicates with the rewriting engine via
9cd3b05d7b70f07a742bbaf548fa4fa2bdbe5ce6noodl <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive function lookup, it expects one argument via <code>STDIN</code>, and
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive should return one new-line terminated response string on
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>STDOUT</code>. If there is no corresponding lookup value, the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive 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
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding <p>This feature utilizes the <code>rewrite-map</code> mutex,
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding which is required for reliable communication with the program.
b24c77ceb4cea5ffa92536e19f0aa83608960dc4fielding 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>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem <div class="example"><h3>Rewrite configuration</h3><p><code>
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem RewriteRule - ${d2u:%{REQUEST_URI}}
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem $| = 1; # Turn off I/O buffering<br />
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem while (<STDIN>) {<br />
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem s/-/_/g; # Replace dashes with underscores<br />
5528d1a30ae8560e2d7a96d734ffe31500dc6113rpluem print $_;<br />
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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li>Be sure to turn off buffering in your program. In Perl this is done
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveby the second line in the example script: <code>$| = 1;</code> This will
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveof course vary in other languages. Buffered I/O will cause httpd to wait
0834a50e694f91f4bf20ddf030fd0812e65cafc7rbowenfor the output, and so it will hang.</li>
0834a50e694f91f4bf20ddf030fd0812e65cafc7rbowen<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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
8cb1b3a3753304d51919865f588cbe19cbd0182arbowen <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
8cb1b3a3753304d51919865f588cbe19cbd0182arbowen used, the MapSource is a SQL SELECT statement that takes a single
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive argument and returns a single value.</p>
e67969aeb443b18bbb3837690c4010c3f1961842jim <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>
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<p class="apache">Copyright 2010 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>
9970ad80054f477c708284a0d030a5bd26e412a9covener<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>