rewritemap.html.en revision 83f3471f5de14ca3def6d7935cd1af1604874bfd
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This file is generated from xml source: DO NOT EDIT
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>Using RewriteMap - Apache HTTP Server</title>
<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<body id="manual-page"><div id="page-header">
<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>
<p class="apache">Apache HTTP Server Version 2.3</p>
<div id="path">
<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>
<div class="toplang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
</div>
<p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
the use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
and provides examples of each of the various <code>RewriteMap</code> types.</p>
<div class="warning">Note that many of these examples won't work unchanged in your
particular server configuration, so it's important that you understand
them, rather than merely cutting and pasting the examples into your
configuration.</div>
</div>
<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
</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>
<div class="section">
<h2><a name="introduction" id="introduction">Introduction</a></h2>
<p>
The <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
defines an external function which can be called in the context of
<code class="directive"><a href="/mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
perform rewriting that is too complicated, or too specialized to be
performed just by regular expressions. The source of this lookup can
be any of the types listed in the sections below, and enumerated in
the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
documentation.</p>
<p>The syntax of the <code>RewriteMap</code> directive is as
follows:</p>
<div class="example"><p><code>
RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
</code></p></div>
<p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
arbitray name that you assign to the map, and which you will use in
directives later on. Arguments are passed to the map via the
following syntax:</p>
<p class="indent">
<strong>
<code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
<code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
<em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
</strong>
</p>
<p>When such a construct occurs, the map <em>MapName</em> is
consulted and the key <em>LookupKey</em> is looked-up. If the
key is found, the map-function construct is substituted by
<em>SubstValue</em>. If the key is not found then it is
substituted by <em>DefaultValue</em> or by the empty string
if no <em>DefaultValue</em> was specified.</p>
<p>For example, you might define a
<code class="directive">RewriteMap</code> as:</p>
<div class="example"><p><code>
</code></p></div>
<p>You would then be able to use this map in a
<code class="directive">RewriteRule</code> as follows:</p>
<div class="example"><p><code>
RewriteRule ^/ex/(.*) ${examplemap:$1}
</code></p></div>
<p>The sections that follow describe the various <em>MapType</em>s that
may be used, and give examples of each.</p>
<div class="section">
<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
<p>MapType: <code>txt</code>, MapSource: Unix filesystem
path to valid regular file</p>
<p>This is the standard rewriting map feature where the
<em>MapSource</em> is a plain ASCII file containing
either blank lines, comment lines (starting with a '#'
character) or pairs like the following - one per
line.</p>
<p class="indent">
<strong>
<em>MatchingKey</em>
<em>SubstValue</em>
</strong>
</p>
<div class="example"><h3>Example</h3><pre>
##
## map.txt -- rewriting map
##
Ralf.S.Engelschall rse # Bastard Operator From Hell
Mr.Joe.Average joe # Mr. Average
</pre></div>
<div class="example"><p><code>
</code></p></div>
<div class="section">
<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
<p>MapType: <code>rnd</code>, MapSource: Unix filesystem
path to valid regular file</p>
<p>This is identical to the Standard Plain Text variant
above but with a special post-processing feature: After
looking up a value it is parsed according to contained
``<code>|</code>'' characters which have the meaning of
``or''. In other words they indicate a set of
alternatives from which the actual returned value is
chosen randomly. For example, you might use the following map
file and directives to provide a random load balancing between
several back-end server, via a reverse-proxy. Images are sent
to one of the servers in the 'static' pool, while everything
else is sent to one of the 'dynamic' pool.</p>
<p>Example:</p>
<div class="example"><h3>Rewrite map file</h3><pre>
##
## map.txt -- rewriting map
##
static www1|www2|www3|www4
dynamic www5|www6
</pre></div>
<div class="example"><h3>Configuration directives</h3><p><code>
<br />
RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
[NC,P,L]<br />
RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
</code></p></div>
<div class="section">
<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
<p>MapType:
<code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
path to valid regular file</p>
<p>Here the source is a binary format DBM file containing
the same contents as a <em>Plain Text</em> format file, but
in a special representation which is optimized for really
fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
db depending on <a href="/install.html#dbm">compile-time
settings</a>. If the <em>type</em> is omitted, the
compile-time default will be chosen.</p>
<p>To create a dbm file from a source text file, use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
<div class="example"><p><code>
$ httxt2dbm -i mapfile.txt -o mapfile.map
</code></p></div>
<div class="section">
<h2><a name="int" id="int">int: Internal Function</a></h2>
<p>
MapType: <code>int</code>, MapSource: Internal Apache httpd
function</p>
<p>Here, the source is an internal Apache httpd function.
Currently you cannot create your own, but the following
functions already exist:</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>
<div class="section">
<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
<p>MapType: <code>prg</code>, MapSource: Unix filesystem path to valid regular file </p>
<p>Here the source is a program, not a map file. To
create it you can use a language of your choice, but
the result has to be an executable program (either
object-code or a script with the magic cookie trick
line).</p><p>This program is started once, when the Apache httpd server
is started, and then communicates with the rewriting engine
via its <code>stdin</code> and <code>stdout</code>
file-handles. For each map-function lookup it will
receive the key to lookup as a newline-terminated string
on <code>stdin</code>. It then has to give back the
looked-up value as a newline-terminated string on
<code>stdout</code> or the four-character string
is no corresponding value for the given key).</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>External rewriting programs are not started if they're defined in a
context that does not have <code class="directive">RewriteEngine</code> set to
<code>on</code></p>.
key == value) could be:</p><div class="example"><pre>
$| = 1;
while (<STDIN>) {
# ...put here any transformations or lookups...
print $_;
}
</pre></div><p>But be very careful:</p><ol><li>``<em>Keep it simple, stupid</em>'' (KISS).
If this program hangs, it will cause Apache httpd to hang
when trying to use the relevant rewrite rule.</li><li>A common mistake is to use buffered I/O on
<code>stdout</code>. Avoid this, as it will cause a deadloop!
``<code>$|=1</code>'' is used above, to prevent this.</li></ol></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>MapType: <code>dbd</code> or <code>fastdbd</code>,
MapSource: An SQL SELECT statement that takes a single
argument and returns a single value.</p>
<p>This uses <code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> to implement a rewritemap
by lookup in an SQL database. There are two forms:
<code>fastdbd</code> caches database lookups internally,
<code>dbd</code> doesn't. So <code>dbd</code> incurs a
performance penalty but responds immediately if the database
contents are updated, while <code>fastdbd</code> is more
efficient but won't re-read database contents until server
restart.</p>
<p>If a query returns more than one row, a random row from
the result set is used.</p>
<div class="example"><h3>Example</h3><p><code>
RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
</code></p></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. While you cannot <strong>declare</strong> a map in
per-directory context it is of course possible to
<strong>use</strong> this map in per-directory context. </p>
<div class="note"><h3>Note</h3> For plain text and DBM format files the
looked-up keys are cached in-core until the <code>mtime</code> of the
mapfile changes or the server does a restart. This way you can have
map-functions in rules which are used for <strong>every</strong>
request. This is no problem, because the external lookup only happens
once!
</div>
</div></div>
<div class="bottomlang">
<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
</div><div id="footer">
<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>
<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>
</body></html>