rewritemap.html.en revision 9c1260efa52c82c2a58e5b5f20cd6902563d95f5
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><!--
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive This file is generated from xml source: DO NOT EDIT
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
530eba85dbd41b8a0fa5255d3648d1440199a661slive<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<link href="/images/favicon.ico" rel="shortcut icon" /></head>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
18b4b0fd6056093002ddef488636bf5ebe415ef0erikabele<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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<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,
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveand provides examples of each of the various <code>RewriteMap</code> types.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <div class="warning">Note that many of these examples won't work unchanged in your
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveparticular server configuration, so it's important that you understand
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivethem, rather than merely cutting and pasting the examples into your
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveconfiguration.</div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive</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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<h2><a name="introduction" id="introduction">Introduction</a></h2>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive defines an external function which can be called in the context of
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive perform rewriting that is too complicated, or too specialized to be
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive performed just by regular expressions. The source of this lookup can
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive be any of the types listed in the sections below, and enumerated in
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive documentation.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The syntax of the <code>RewriteMap</code> directive is as
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive follows:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd arbitray name that you assign to the map, and which you will use in
130d299c4b2b15be45532a176604c71fdc7bea5bnd directives later on. Arguments are passed to the map via the
130d299c4b2b15be45532a176604c71fdc7bea5bnd following syntax:</p>
130d299c4b2b15be45532a176604c71fdc7bea5bnd <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
130d299c4b2b15be45532a176604c71fdc7bea5bnd <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
130d299c4b2b15be45532a176604c71fdc7bea5bnd <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When such a construct occurs, the map <em>MapName</em> is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive consulted and the key <em>LookupKey</em> is looked-up. If the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive key is found, the map-function construct is substituted by
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <em>SubstValue</em>. If the key is not found then it is
003f0c9fda6664daf5092a0e42f65ede20098153slive substituted by <em>DefaultValue</em> or by the empty string
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>For example, you might define a
003f0c9fda6664daf5092a0e42f65ede20098153slive <p>You would then be able to use this map in a
003f0c9fda6664daf5092a0e42f65ede20098153slive <code class="directive">RewriteRule</code> as follows:</p>
003f0c9fda6664daf5092a0e42f65ede20098153slive RewriteRule ^/ex/(.*) ${examplemap:$1}
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<p>A default value can be specified in the event that nothing is found
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cndin the map:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<div class="note"><h3>Per-directory and .htaccess context</h3>
130d299c4b2b15be45532a176604c71fdc7bea5bnd<Directory> sections or <code>.htaccess</code> files. You must
130d299c4b2b15be45532a176604c71fdc7bea5bnddeclare the map in server or virtualhost context. You may use the map,
130d299c4b2b15be45532a176604c71fdc7bea5bnd<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
1a3f62ca37273a15a06bb94a61d3c6fcf4bf38c9rbowenmay 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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>txt</code>is used, the MapSource is a filesystem path to a
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd plain-text mapping file, containing space-separated key/value pair
530eba85dbd41b8a0fa5255d3648d1440199a661slive 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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive # 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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive returned.</p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <p>For example, we might use a mapfile to translate product names to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive product IDs for easier-to-remember URLs, using the following
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd recipe:</p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <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]
58699879a562774640b95e9eedfd891f336e38c2nd <p>We assume here that the <code>prods.php</code> script knows what
58699879a562774640b95e9eedfd891f336e38c2nd to do when it received an argument of <code>id=NOTFOUND</code> when
58699879a562774640b95e9eedfd891f336e38c2nd a product is not found in the lookup map.</p>
58699879a562774640b95e9eedfd891f336e38c2nd <p>The file <code>/etc/apache2/productmap.txt</code> then contains
58699879a562774640b95e9eedfd891f336e38c2nd the following:</p>
58699879a562774640b95e9eedfd891f336e38c2nd## productmap.txt - Product to ID map file
58699879a562774640b95e9eedfd891f336e38c2ndtelevision 993
58699879a562774640b95e9eedfd891f336e38c2ndfishingrod 043
58699879a562774640b95e9eedfd891f336e38c2ndbasketball 418
58699879a562774640b95e9eedfd891f336e38c2ndtelephone 328
58699879a562774640b95e9eedfd891f336e38c2nd <p>Thus, when <code>http://example.com/product/television</code> is
58699879a562774640b95e9eedfd891f336e38c2nd requested, the <code>RewriteRule</code> is applied, and the request
58699879a562774640b95e9eedfd891f336e38c2nd is internally mapped to <code>/prods.php?id=993</code>.</p>
58699879a562774640b95e9eedfd891f336e38c2nd The example given is crafted to be used in server or virtualhost
58699879a562774640b95e9eedfd891f336e38c2nd scope. If you're planning to use this in a <code>.htaccess</code>
58699879a562774640b95e9eedfd891f336e38c2nd file, you'll need to remove the leading slash from the rewrite
58699879a562774640b95e9eedfd891f336e38c2nd pattern in order for it to match anything:
58699879a562774640b95e9eedfd891f336e38c2nd RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
58699879a562774640b95e9eedfd891f336e38c2nd The looked-up keys are cached by httpd until the <code>mtime</code>
58699879a562774640b95e9eedfd891f336e38c2nd (modified time) of the mapfile changes, or the httpd server is
58699879a562774640b95e9eedfd891f336e38c2nd restarted. This ensures better performance on maps that are called
58699879a562774640b95e9eedfd891f336e38c2nd by many requests.
58699879a562774640b95e9eedfd891f336e38c2nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
58699879a562774640b95e9eedfd891f336e38c2nd<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
58699879a562774640b95e9eedfd891f336e38c2nd <p>When a MapType of <code>rnd</code> is used, the MapSource is a
58699879a562774640b95e9eedfd891f336e38c2nd filesystem path to a plain-text mapping file, each line of which
58699879a562774640b95e9eedfd891f336e38c2nd contains a key, and one or more values separated by <code>|</code>.
58699879a562774640b95e9eedfd891f336e38c2nd One of these values will be chosen at random if the key is
58699879a562774640b95e9eedfd891f336e38c2nd matched.</p>
58699879a562774640b95e9eedfd891f336e38c2nd <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
003f0c9fda6664daf5092a0e42f65ede20098153slive to one of the servers in the 'static' pool, while everything
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive else is sent to one of the 'dynamic' pool.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive## map.txt -- rewriting map
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivestatic www1|www2|www3|www4
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivedynamic www5|www6
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <div class="example"><h3>Configuration directives</h3><p><code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive 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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive specified hostnames at random, which is then used in the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>If you wanted to have one of the servers more likely to be chosen
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive (for example, if one of the server has more memory than the others,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive and so can handle more requests) simply list it more times in the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive map file.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivestatic www1|www1|www2|www3|www4
9ed9eaf871c58d281af02e76125ceadb5060afa5nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>When a MapType of <code>dbm</code> is used, the MapSource is a
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive filesystem path to a DBM database file containing key/value pairs to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive be used in the mapping. This works exactly the same way as the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>txt</code> map, but is much faster, because a DBM is indexed,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive whereas a text file is not. This allows more rapid access to the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive desired key.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>You may optionally specify a particular dbm type:</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>To create a dbm file, first create a text map file as described
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<p>You can then reference the resulting file in your
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<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
9ed9eaf871c58d281af02e76125ceadb5060afa5ndnormal, 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.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<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
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:
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive 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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Translates hex-encodings in the key back to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive special characters.</li>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive 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>:
9ed9eaf871c58d281af02e76125ceadb5060afa5nd <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteMap lc int:tolower<br />
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <p>Please note that the example offered here is for
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd illustration purposes only, and is not a recommendation. If you want
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive to make URLs case-insensitive, consider using
1c9f7cdf2e1bc8313e559a96638c3c36e3143791yoshiki <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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive filesystem path to an executable program which will providing the
003f0c9fda6664daf5092a0e42f65ede20098153slive mapping behavior. This can be a compiled binary file, or a program
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive in an interpreted language such as Perl or Python.</p>
530eba85dbd41b8a0fa5255d3648d1440199a661slive <p>This program is started once, when the Apache HTTP Server is
530eba85dbd41b8a0fa5255d3648d1440199a661slive started, and then communicates with the rewriting engine via
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>External rewriting programs are not started if they're defined in
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>This feature utilizes the <code>rewrite-map</code> mutex,
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive which is required for reliable communication with the program.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive The mutex mechanism and lock file can be configured with the
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>A simple example is shown here which will replace all dashes with
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes underscores in a request URI.</p>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes <div class="example"><h3>Rewrite configuration</h3><p><code>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes RewriteRule - ${d2u:%{REQUEST_URI}}
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes <div class="example"><h3>dash2under.pl</h3><p><code>
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes $| = 1; # Turn off I/O buffering<br />
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes while (<STDIN>) {<br />
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes s/-/_/g; # Replace dashes with underscores<br />
4c7bdb15764021d39e486adb7bc2166d3f683773bnicholes 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
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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<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
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive used, the MapSource is a SQL SELECT statement that takes a single
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive argument and returns a single value.</p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd the right database for this statement to be executed.</p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd <p>There are two forms of this MapType.
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive Using a MapType of <code>dbd</code> causes the query to be
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive executed with each map request, while using <code>fastdbd</code>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive caches the database lookups internally. So, while
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <code>fastdbd</code> is more efficient, and therefore faster, it
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive won't pick up on changes to the database until the server is
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive restarted.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <p>If a query returns more than one row, a random row from
80c4526970a11f37c0f8e3b82afdf03902dac3f3slivethe result set is used.</p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3sliveRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
003f0c9fda6664daf5092a0e42f65ede20098153slive </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <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>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive per-directory context (<code>.htaccess</code> files or
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <Directory> blocks) it is possible to
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive <strong>use</strong> this map in per-directory context. </p>
80c4526970a11f37c0f8e3b82afdf03902dac3f3slive<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<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>
a7f40ca49262952d6dd69d021cf5b0c2b452ae4cnd<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>