rewritemap.html.en revision 95ab37c71e0d89443389909b290c98f8fc80ec5e
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive This file is generated from xml source: DO NOT EDIT
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
8a75fe091731dcfd6581bd8a2423ba654b4e8e17nd<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" />
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<script src="/style/scripts/prettify.js" type="text/javascript">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<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>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<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>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndthe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndand provides examples of each of the various <code>RewriteMap</code> types.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <div class="warning">Note that many of these examples won't work unchanged in your
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndparticular server configuration, so it's important that you understand
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndthem, rather than merely cutting and pasting the examples into your
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndconfiguration.</div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
aedd0bf93c729eb723b1eeffccf46bf0117ff0ederikabele<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</ul><h3>See also</h3><ul class="seealso"><li><a href="/mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="introduction" id="introduction">Introduction</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd defines an external function which can be called in the context of
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd perform rewriting that is too complicated, or too specialized to be
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd performed just by regular expressions. The source of this lookup can
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd be any of the types listed in the sections below, and enumerated in
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd documentation.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>The syntax of the <code>RewriteMap</code> directive is as
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd follows:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<pre class="prettyprint lang-config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd arbitray name that you assign to the map, and which you will use in
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd directives later on. Arguments are passed to the map via the
89ccb0f86491cc768e39f5c3c95a23f45a81eb3ckess following syntax:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>When such a construct occurs, the map <em>MapName</em> is
89ccb0f86491cc768e39f5c3c95a23f45a81eb3ckess consulted and the key <em>LookupKey</em> is looked-up. If the
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd key is found, the map-function construct is substituted by
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd substituted by <em>DefaultValue</em> or by the empty string
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>For example, you might define a
199a8ee5984e3708982fab1ba6ebb0a5feaea90cnd <pre class="prettyprint lang-config">RewriteMap examplemap txt:/path/to/file/map.txt</pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>You would then be able to use this map in a
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code class="directive">RewriteRule</code> as follows:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1}</pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p>A default value can be specified in the event that nothing is found
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndin the map:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="note"><h3>Per-directory and .htaccess context</h3>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<Directory> sections or <code>.htaccess</code> files. You must
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnddeclare the map in server or virtualhost context. You may use the map,
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<code>RewriteCond</code> directives in those scopes. You just can't
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p>The sections that follow describe the various <em>MapType</em>s that
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndmay be used, and give examples of each.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd plain-text mapping file, containing space-separated key/value pair
8af1f06ba59fdda01b4a5c2fea560c2bf0569addslive per line. Optionally, a line may be contain a comment, starting with
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd a '#' character.</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>For example, the following might be valid entries in a map
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd # Comment line<br />
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz <p>When the RewriteMap is invoked the argument is looked for in the
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd first argument of a line, and, if found, the substitution value is
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz returned.</p>
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd <p>For example, we might use a mapfile to translate product names to
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd product IDs for easier-to-remember URLs, using the following
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd recipe:</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndRewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>We assume here that the <code>prods.php</code> script knows what
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd to do when it received an argument of <code>id=NOTFOUND</code> when
bbcbf978a3074512c627c797fedcb30eeab7b39dslive a product is not found in the lookup map.</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>The file <code>/etc/apache2/productmap.txt</code> then contains
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd the following:</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndtelevision 993<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndstereo 198<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndfishingrod 043<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndbasketball 418<br />
27c043596ef154c881a7d572c65d32cbf537685cndtelephone 328
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>Thus, when <code>http://example.com/product/television</code> is
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd requested, the <code>RewriteRule</code> is applied, and the request
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd is internally mapped to <code>/prods.php?id=993</code>.</p>
b73a2be324e0b7fda7671ffc1e580a83a2af0d61nd The example given is crafted to be used in server or virtualhost
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd scope. If you're planning to use this in a <code>.htaccess</code>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd file, you'll need to remove the leading slash from the rewrite
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd pattern in order for it to match anything:
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <pre class="prettyprint lang-config">RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]</pre>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd The looked-up keys are cached by httpd until the <code>mtime</code>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd (modified time) of the mapfile changes, or the httpd server is
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd restarted. This ensures better performance on maps that are called
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd by many requests.
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>When a MapType of <code>rnd</code> is used, the MapSource is a
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd filesystem path to a plain-text mapping file, each line of which
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd contains a key, and one or more values separated by <code>|</code>.
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd One of these values will be chosen at random if the key is
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd matched.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>For example, you might use the following map
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd file and directives to provide a random load balancing between
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd several back-end servers, via a reverse-proxy. Images are sent
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd to one of the servers in the 'static' pool, while everything
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd else is sent to one of the 'dynamic' pool.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndstatic www1|www2|www3|www4<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnddynamic www5|www6
However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
<p class="apache">Copyright 2012 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>
<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><script type="text/javascript">