rewritemap.html.en revision cde7900bb5b14f5bd981ad98b0215c85b915bef7
0a3142725875ea286597e083547d34d98f8c1f2drbowen<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
0a3142725875ea286597e083547d34d98f8c1f2drbowen<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0a3142725875ea286597e083547d34d98f8c1f2drbowen This file is generated from xml source: DO NOT EDIT
0a3142725875ea286597e083547d34d98f8c1f2drbowen XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
0a3142725875ea286597e083547d34d98f8c1f2drbowen<link href="/images/favicon.ico" rel="shortcut icon" /></head>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>This document supplements the <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
0a3142725875ea286597e083547d34d98f8c1f2drbowenthe use of the <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
0a3142725875ea286597e083547d34d98f8c1f2drbowenand provides examples of each of the various <code>RewriteMap</code> types.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <div class="warning">Note that many of these examples won't work unchanged in your
0a3142725875ea286597e083547d34d98f8c1f2drbowenparticular server configuration, so it's important that you understand
0a3142725875ea286597e083547d34d98f8c1f2drbowenthem, rather than merely cutting and pasting the examples into your
0a3142725875ea286597e083547d34d98f8c1f2drbowenconfiguration.</div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<li><img alt="" src="/images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#int">int: Internal Function</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<li><img alt="" src="/images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<li><img alt="" src="/images/down.gif" /> <a href="#summary">Summary</a></li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen</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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<h2><a name="introduction" id="introduction">Introduction</a></h2>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>The <code class="directive">RewriteMap</code> directive defines a
0a3142725875ea286597e083547d34d98f8c1f2drbowen substitution strings by the mapping-functions to
0a3142725875ea286597e083547d34d98f8c1f2drbowen insert/substitute fields through a key lookup. The source of
0a3142725875ea286597e083547d34d98f8c1f2drbowen this lookup can be of various types.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
0a3142725875ea286597e083547d34d98f8c1f2drbowen the name of the map and will be used to specify a
0a3142725875ea286597e083547d34d98f8c1f2drbowen mapping-function for the substitution strings of a rewriting
0a3142725875ea286597e083547d34d98f8c1f2drbowen rule via one of the following constructs:</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>When such a construct occurs, the map <em>MapName</em> is
0a3142725875ea286597e083547d34d98f8c1f2drbowen consulted and the key <em>LookupKey</em> is looked-up. If the
0a3142725875ea286597e083547d34d98f8c1f2drbowen key is found, the map-function construct is substituted by
0a3142725875ea286597e083547d34d98f8c1f2drbowen <em>SubstValue</em>. If the key is not found then it is
0a3142725875ea286597e083547d34d98f8c1f2drbowen substituted by <em>DefaultValue</em> or by the empty string
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>For example, you might define a
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>You would then be able to use this map in a
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code class="directive">RewriteRule</code> as follows:</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen RewriteRule ^/ex/(.*) ${examplemap:$1}
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>The following combinations for <em>MapType</em> and
0a3142725875ea286597e083547d34d98f8c1f2drbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>MapType: <code>txt</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>This is the standard rewriting map feature where the
0a3142725875ea286597e083547d34d98f8c1f2drbowen either blank lines, comment lines (starting with a '#'
0a3142725875ea286597e083547d34d98f8c1f2drbowen character) or pairs like the following - one per
0a3142725875ea286597e083547d34d98f8c1f2drbowen## map.txt -- rewriting map
0a3142725875ea286597e083547d34d98f8c1f2drbowenRalf.S.Engelschall rse # Bastard Operator From Hell
0a3142725875ea286597e083547d34d98f8c1f2drbowenMr.Joe.Average joe # Mr. Average
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>This is identical to the Standard Plain Text variant
0a3142725875ea286597e083547d34d98f8c1f2drbowen above but with a special post-processing feature: After
0a3142725875ea286597e083547d34d98f8c1f2drbowen looking up a value it is parsed according to contained
0a3142725875ea286597e083547d34d98f8c1f2drbowen ``<code>|</code>'' characters which have the meaning of
0a3142725875ea286597e083547d34d98f8c1f2drbowen ``or''. In other words they indicate a set of
0a3142725875ea286597e083547d34d98f8c1f2drbowen alternatives from which the actual returned value is
0a3142725875ea286597e083547d34d98f8c1f2drbowen chosen randomly. For example, you might use the following map
0a3142725875ea286597e083547d34d98f8c1f2drbowen file and directives to provide a random load balancing between
0a3142725875ea286597e083547d34d98f8c1f2drbowen several back-end server, via a reverse-proxy. Images are sent
0a3142725875ea286597e083547d34d98f8c1f2drbowen to one of the servers in the 'static' pool, while everything
0a3142725875ea286597e083547d34d98f8c1f2drbowen else is sent to one of the 'dynamic' pool.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen## map.txt -- rewriting map
0a3142725875ea286597e083547d34d98f8c1f2drbowenstatic www1|www2|www3|www4
0a3142725875ea286597e083547d34d98f8c1f2drbowendynamic www5|www6
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <div class="example"><h3>Configuration directives</h3><p><code>
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
0a3142725875ea286597e083547d34d98f8c1f2drbowen[NC,P,L]<br />
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>MapType:
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>Here the source is a binary format DBM file containing
0a3142725875ea286597e083547d34d98f8c1f2drbowen the same contents as a <em>Plain Text</em> format file, but
0a3142725875ea286597e083547d34d98f8c1f2drbowen in a special representation which is optimized for really
0a3142725875ea286597e083547d34d98f8c1f2drbowen fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
0a3142725875ea286597e083547d34d98f8c1f2drbowen db depending on <a href="/install.html#dbm">compile-time
0a3142725875ea286597e083547d34d98f8c1f2drbowen compile-time default will be chosen.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>To create a dbm file from a source text file, use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="int" id="int">int: Internal Function</a></h2>
0a3142725875ea286597e083547d34d98f8c1f2drbowen MapType: <code>int</code>, MapSource: Internal Apache httpd
0a3142725875ea286597e083547d34d98f8c1f2drbowen function</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>Here, the source is an internal Apache httpd function.
0a3142725875ea286597e083547d34d98f8c1f2drbowen Currently you cannot create your own, but the following
0a3142725875ea286597e083547d34d98f8c1f2drbowen functions already exist:</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Converts the key to all upper case.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Converts the key to all lower case.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates special characters in the key to
0a3142725875ea286597e083547d34d98f8c1f2drbowen hex-encodings.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen Translates hex-encodings in the key back to
0a3142725875ea286597e083547d34d98f8c1f2drbowen special characters.</li>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2><p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen MapType: <code>prg</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </p><p>Here the source is a program, not a map file. To
0a3142725875ea286597e083547d34d98f8c1f2drbowen create it you can use a language of your choice, but
0a3142725875ea286597e083547d34d98f8c1f2drbowen the result has to be an executable program (either
0a3142725875ea286597e083547d34d98f8c1f2drbowen object-code or a script with the magic cookie trick
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen line).</p><p>This program is started once, when the Apache httpd server
0a3142725875ea286597e083547d34d98f8c1f2drbowen is started, and then communicates with the rewriting engine
0a3142725875ea286597e083547d34d98f8c1f2drbowen file-handles. For each map-function lookup it will
0a3142725875ea286597e083547d34d98f8c1f2drbowen receive the key to lookup as a newline-terminated string
0a3142725875ea286597e083547d34d98f8c1f2drbowen looked-up value as a newline-terminated string on
0a3142725875ea286597e083547d34d98f8c1f2drbowen ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen is no corresponding value for the given key).</p><p>This feature utilizes the <code>rewrite-map</code> mutex,
0a3142725875ea286597e083547d34d98f8c1f2drbowen which is required for reliable communication with the program.
0a3142725875ea286597e083547d34d98f8c1f2drbowen The mutex mechanism and lock file can be configured with the
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen context that does not have <code class="directive">RewriteEngine</code> set to
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen key == value) could be:</p><div class="example"><pre>
0a3142725875ea286597e083547d34d98f8c1f2drbowenwhile (<STDIN>) {
0a3142725875ea286597e083547d34d98f8c1f2drbowen # ...put here any transformations or lookups...
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen</pre></div><p>But be very careful:</p><ol><li>``<em>Keep it simple, stupid</em>'' (KISS).
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenIf this program hangs, it will cause Apache httpd to hang
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenwhen trying to use the relevant rewrite rule.</li><li>A common mistake is to use buffered I/O on
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<code>stdout</code>. Avoid this, as it will cause a deadloop!
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen``<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>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>MapType: <code>dbd</code> or <code>fastdbd</code>,
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenMapSource: An SQL SELECT statement that takes a single
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen argument and returns a single value.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>This uses <code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> to implement a rewritemap
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenby lookup in an SQL database. There are two forms:
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<code>fastdbd</code> caches database lookups internally,
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen<code>dbd</code> doesn't. So <code>dbd</code> incurs a
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenperformance penalty but responds immediately if the database
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowencontents are updated, while <code>fastdbd</code> is more
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenefficient but won't re-read database contents until server
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenrestart.</p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>If a query returns more than one row, a random row from
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowenthe result set is used.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <p>The <code class="directive">RewriteMap</code> directive can occur more than
0a3142725875ea286597e083547d34d98f8c1f2drbowen once. For each mapping-function use one
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code class="directive">RewriteMap</code> directive to declare its rewriting
0a3142725875ea286597e083547d34d98f8c1f2drbowen mapfile. While you cannot <strong>declare</strong> a map in
0a3142725875ea286597e083547d34d98f8c1f2drbowen per-directory context it is of course possible to
0a3142725875ea286597e083547d34d98f8c1f2drbowen <strong>use</strong> this map in per-directory context. </p>
cde7900bb5b14f5bd981ad98b0215c85b915bef7rbowen <div class="note"><h3>Note</h3> For plain text and DBM format files the
0a3142725875ea286597e083547d34d98f8c1f2drbowenlooked-up keys are cached in-core until the <code>mtime</code> of the
0a3142725875ea286597e083547d34d98f8c1f2drbowenmapfile changes or the server does a restart. This way you can have
0a3142725875ea286597e083547d34d98f8c1f2drbowenmap-functions in rules which are used for <strong>every</strong>
0a3142725875ea286597e083547d34d98f8c1f2drbowenrequest. This is no problem, because the external lookup only happens
0a3142725875ea286597e083547d34d98f8c1f2drbowen<p><span>Available Languages: </span><a href="/en/rewrite/rewritemap.html" title="English"> en </a></p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<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>