rewritemap.html.en revision 95ab37c71e0d89443389909b290c98f8fc80ec5e
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<?xml version="1.0" encoding="ISO-8859-1"?>
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 -->
1506e77ef38e9fed0fc0b180ee505b6a02ca98f3slive<title>Using RewriteMap - Apache HTTP Server</title>
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</script>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<body id="manual-page"><div id="page-header">
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<p class="apache">Apache HTTP Server Version 2.5</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<img alt="" src="/images/feather.gif" /></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="/images/left.gif" /></a></div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div id="path">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="toplang">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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
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
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd </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<div class="section">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="introduction" id="introduction">Introduction</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>
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
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>The syntax of the <code>RewriteMap</code> directive is as
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd follows:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<pre class="prettyprint lang-config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p class="indent">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <strong>
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 </strong>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd </p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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 <em>SubstValue</em>. If the key is not found then it is
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd substituted by <em>DefaultValue</em> or by the empty string
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd if no <em>DefaultValue</em> was specified.</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <p>For example, you might define a
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <code class="directive">RewriteMap</code> as:</p>
199a8ee5984e3708982fab1ba6ebb0a5feaea90cnd <pre class="prettyprint lang-config">RewriteMap examplemap txt:/path/to/file/map.txt</pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p>A default value can be specified in the event that nothing is found
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndin the map:</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</pre>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<div class="note"><h3>Per-directory and .htaccess context</h3>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndThe <code>RewriteMap</code> directive may not be used in
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd&lt;Directory&gt; sections or <code>.htaccess</code> files. You must
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnddeclare the map in server or virtualhost context. You may use the map,
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndonce created, in your <code>RewriteRule</code> and
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<code>RewriteCond</code> directives in those scopes. You just can't
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<strong>declare</strong> it in those scopes.
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</p>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd</div>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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<div class="section">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>For example, the following might be valid entries in a map
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd file.</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz <p class="indent">
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>
35ffb30f57f777dbf3f17c5a5ddf706559942c16nd
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>
1f53e295ebd19aed1767d12da7abfab9936c148cjerenkrantz
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>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd<p><strong>Product to ID configuration</strong></p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <pre class="prettyprint lang-config">
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndRewriteMap product2id txt:/etc/apache2/productmap.txt
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndRewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd </pre>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
d1e705efc6b288edbe466fd1af69d228f508361end
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
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>The file <code>/etc/apache2/productmap.txt</code> then contains
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd the following:</p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <div class="example"><h3>Product to ID map</h3><p><code>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd##<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd## productmap.txt - Product to ID map file<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd##<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndtelevision 993<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndstereo 198<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndfishingrod 043<br />
8a72c24379e10c3f3d0dfe352bf15e45ee65c179ndbasketball 418<br />
27c043596ef154c881a7d572c65d32cbf537685cndtelephone 328
bbcbf978a3074512c627c797fedcb30eeab7b39dslive </code></p></div>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
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
b73a2be324e0b7fda7671ffc1e580a83a2af0d61nd <div class="note"><h3>Note: .htaccess files</h3>
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
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd </div>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <div class="note"><h3>Cached lookups</h3>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd <p>
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 </p>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd </div>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
8a72c24379e10c3f3d0dfe352bf15e45ee65c179nd<div class="section">
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
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
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>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd <div class="example"><h3>Rewrite map file</h3><p><code>
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd##<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd## map.txt -- rewriting map<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd##<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafndstatic www1|www2|www3|www4<br />
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnddynamic www5|www6
02b39e6d8d0bf5fc0014bb1b4826b05db879ddafnd </code></p></div>
f46a61fedb6c867aaa1ebad55222adce7d9c95f6kess<p><strong>Configuration directives</strong></p>
<pre class="prettyprint lang-config">
RewriteMap servers rnd:/path/to/file/map.txt
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
</pre>
<p>So, when an image is requested and the first of these rules is
matched, <code>RewriteMap</code> looks up the string
<code>static</code> in the map file, which returns one of the
specified hostnames at random, which is then used in the
<code>RewriteRule</code> target.</p>
<p>If you wanted to have one of the servers more likely to be chosen
(for example, if one of the server has more memory than the others,
and so can handle more requests) simply list it more times in the
map file.</p>
<div class="example"><p><code>
static www1|www1|www2|www3|www4
</code></p></div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
<p>When a MapType of <code>dbm</code> is used, the MapSource is a
filesystem path to a DBM database file containing key/value pairs to
be used in the mapping. This works exactly the same way as the
<code>txt</code> map, but is much faster, because a DBM is indexed,
whereas a text file is not. This allows more rapid access to the
desired key.</p>
<p>You may optionally specify a particular dbm type:</p>
<pre class="prettyprint lang-config">
RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
</pre>
<p>The type can be sdbm, gdbm, ndbm or db.
However, it is recommended that you just use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
provided with Apache HTTP Server, as it will use the correct DBM library,
matching the one that was used when httpd itself was built.</p>
<p>To create a dbm file, first create a text map file as described
in the <a href="#txt">txt</a> section. Then run
<code>httxt2dbm</code>:</p>
<div class="example"><p><code>
$ httxt2dbm -i mapfile.txt -o mapfile.map
</code></p></div>
<p>You can then reference the resulting file in your
<code>RewriteMap</code> directive:</p>
<pre class="prettyprint lang-config">
RewriteMap mapname dbm:/etc/apache/mapfile.map
</pre>
<div class="note">
<p>Note that with some dbm types, more than one file is generated, with
a common base name. For example, you may have two files named
<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
normal, and you need only use the base name <code>mapfile.map</code> in
your <code>RewriteMap</code> directive.</p>
</div>
<div class="note"><h3>Cached lookups</h3>
<p>
The looked-up keys are cached by httpd until the <code>mtime</code>
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
</p>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="int" id="int">int: Internal Function</a></h2>
<p>When a MapType of <code>int</code> is used, the MapSource is one
of the available internal RewriteMap functions. Module authors can provide
additional internal functions by registering them with the
<code>ap_register_rewrite_mapfunc</code> API.
The functions that are provided by default are:
</p>
<ul>
<li><strong>toupper</strong>:<br />
Converts the key to all upper case.</li>
<li><strong>tolower</strong>:<br />
Converts the key to all lower case.</li>
<li><strong>escape</strong>:<br />
Translates special characters in the key to
hex-encodings.</li>
<li><strong>unescape</strong>:<br />
Translates hex-encodings in the key back to
special characters.</li>
</ul>
<p>
To use one of these functions, create a <code>RewriteMap</code> referencing
the int function, and then use that in your <code>RewriteRule</code>:
</p>
<p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
<pre class="prettyprint lang-config">
RewriteMap lc int:tolower
RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
</pre>
<div class="note">
<p>Please note that the example offered here is for
illustration purposes only, and is not a recommendation. If you want
to make URLs case-insensitive, consider using
<code class="module"><a href="/mod/mod_speling.html">mod_speling</a></code> instead.
</p>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
<p>When a MapType of <code>prg</code> is used, the MapSource is a
filesystem path to an executable program which will providing the
mapping behavior. This can be a compiled binary file, or a program
in an interpreted language such as Perl or Python.</p>
<p>This program is started once, when the Apache HTTP Server is
started, and then communicates with the rewriting engine via
<code>STDIN</code> and <code>STDOUT</code>. That is, for each map
function lookup, it expects one argument via <code>STDIN</code>, and
should return one new-line terminated response string on
<code>STDOUT</code>. If there is no corresponding lookup value, the
map program should return the four-character string
"<code>NULL</code>" to indicate this.</p>
<p>External rewriting programs are not started if they're defined in
a context that does not have <code class="directive"><a href="/mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
<code>on</code>.</p>
<p>This feature utilizes the <code>rewrite-map</code> mutex,
which is required for reliable communication with the program.
The mutex mechanism and lock file can be configured with the
<code class="directive"><a href="/mod/core.html#mutex">Mutex</a></code> directive.</p>
<p>A simple example is shown here which will replace all dashes with
underscores in a request URI.</p>
<p><strong>Rewrite configuration</strong></p>
<pre class="prettyprint lang-config">
RewriteMap d2u prg:/www/bin/dash2under.pl<br />
RewriteRule - ${d2u:%{REQUEST_URI}}
</pre>
<p><strong>dash2under.pl</strong></p>
<pre class="prettyprint lang-perl">
#!/usr/bin/perl
$| = 1; # Turn off I/O buffering
while (&lt;STDIN&gt;) {
s/-/_/g; # Replace dashes with underscores
print $_;
}
</pre>
<div class="note"><h3>Caution!</h3>
<ul>
<li>Keep your rewrite map program as simple as possible. If the program
hangs, it will cause httpd to wait indefinitely for a response from the
map, which will, in turn, cause httpd to stop responding to
requests.</li>
<li>Be sure to turn off buffering in your program. In Perl this is done
by the second line in the example script: <code>$| = 1;</code> This will
of course vary in other languages. Buffered I/O will cause httpd to wait
for the output, and so it will hang.</li>
<li>Remember that there is only one copy of the program, started at
server startup. All requests will need to go through this one bottleneck.
This can cause significant slowdowns if many requests must go through
this process, or if the script itself is very slow.</li>
</ul>
</div>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
<p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
used, the MapSource is a SQL SELECT statement that takes a single
argument and returns a single value.</p>
<p><code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
the right database for this statement to be executed.</p>
<p>There are two forms of this MapType.
Using a MapType of <code>dbd</code> causes the query to be
executed with each map request, while using <code>fastdbd</code>
caches the database lookups internally. So, while
<code>fastdbd</code> is more efficient, and therefore faster, it
won't pick up on changes to the database until the server is
restarted.</p>
<p>If a query returns more than one row, a random row from
the result set is used.</p>
<pre class="prettyprint lang-config"><strong>Example</strong>
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
</pre>
</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="summary" id="summary">Summary</a></h2>
<p>The <code class="directive">RewriteMap</code> directive can occur more than
once. For each mapping-function use one
<code class="directive">RewriteMap</code> directive to declare its rewriting
mapfile.</p>
<p>While you cannot <strong>declare</strong> a map in
per-directory context (<code>.htaccess</code> files or
&lt;Directory&gt; blocks) it is possible to
<strong>use</strong> this map in per-directory context. </p>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
</div><div id="footer">
<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">
if (typeof(prettyPrint) !== undefined) {
prettyPrint();
}
</script>
</body></html>