rewritemap.xml revision 0a3142725875ea286597e083547d34d98f8c1f2d
0a3142725875ea286597e083547d34d98f8c1f2drbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<!-- $LastChangedRevision: 882992 $ -->
0a3142725875ea286597e083547d34d98f8c1f2drbowen Licensed to the Apache Software Foundation (ASF) under one or more
0a3142725875ea286597e083547d34d98f8c1f2drbowen contributor license agreements. See the NOTICE file distributed with
0a3142725875ea286597e083547d34d98f8c1f2drbowen this work for additional information regarding copyright ownership.
0a3142725875ea286597e083547d34d98f8c1f2drbowen The ASF licenses this file to You under the Apache License, Version 2.0
0a3142725875ea286597e083547d34d98f8c1f2drbowen (the "License"); you may not use this file except in compliance with
0a3142725875ea286597e083547d34d98f8c1f2drbowen the License. You may obtain a copy of the License at
0a3142725875ea286597e083547d34d98f8c1f2drbowen Unless required by applicable law or agreed to in writing, software
0a3142725875ea286597e083547d34d98f8c1f2drbowen distributed under the License is distributed on an "AS IS" BASIS,
0a3142725875ea286597e083547d34d98f8c1f2drbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0a3142725875ea286597e083547d34d98f8c1f2drbowen See the License for the specific language governing permissions and
0a3142725875ea286597e083547d34d98f8c1f2drbowen limitations under the License.
0a3142725875ea286597e083547d34d98f8c1f2drbowen<p>This document supplements the <module>mod_rewrite</module>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
0a3142725875ea286597e083547d34d98f8c1f2drbowenthe use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
0a3142725875ea286597e083547d34d98f8c1f2drbowenand provides examples of each of the various <code>RewriteMap</code> types.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<note type="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.</note>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="access.html">Controlling access</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<section id="introduction"><title>Introduction</title>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>The <directive>RewriteMap</directive> 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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <strong><code>${</code> <em>MapName</em> <code>:</code>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>For example, you might define a
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>You would then be able to use this map in a
0a3142725875ea286597e083547d34d98f8c1f2drbowen RewriteRule ^/ex/(.*) ${examplemap:$1}
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>The following combinations for <em>MapType</em> and
0a3142725875ea286597e083547d34d98f8c1f2drbowen <section id="txt"><title>txt: Plain text maps</title>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>MapType: <code>txt</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen<section id="rnd"><title>Randomized Plain Text</title>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
0a3142725875ea286597e083547d34d98f8c1f2drbowen[NC,P,L]<br />
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>To create a dbm file from a source text file, use the <a
0a3142725875ea286597e083547d34d98f8c1f2drbowen href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen MapType: <code>int</code>, MapSource: Internal Apache httpd
0a3142725875ea286597e083547d34d98f8c1f2drbowen function</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<section id="prg"><title>External Rewriting Program</title>
0a3142725875ea286597e083547d34d98f8c1f2drbowen MapType: <code>prg</code>, MapSource: Unix filesystem
0a3142725875ea286597e083547d34d98f8c1f2drbowen path to valid regular file
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen is no corresponding value for the given key).</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <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
0a3142725875ea286597e083547d34d98f8c1f2drbowen <directive module="core">Mutex</directive> directive.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>External rewriting programs are not started if they're defined in a
0a3142725875ea286597e083547d34d98f8c1f2drbowen context that does not have <directive>RewriteEngine</directive> set to
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
0a3142725875ea286597e083547d34d98f8c1f2drbowen key == value) could be:</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowenwhile (<STDIN>) {
0a3142725875ea286597e083547d34d98f8c1f2drbowen # ...put here any transformations or lookups...
0a3142725875ea286597e083547d34d98f8c1f2drbowen If this program hangs, it will cause Apache httpd to hang
0a3142725875ea286597e083547d34d98f8c1f2drbowen when trying to use the relevant rewrite rule.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <li>A common mistake is to use buffered I/O on
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code>stdout</code>. Avoid this, as it will cause a deadloop!
0a3142725875ea286597e083547d34d98f8c1f2drbowen ``<code>$|=1</code>'' is used above, to prevent this.</li>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>MapType: <code>dbd</code> or <code>fastdbd</code>,
0a3142725875ea286597e083547d34d98f8c1f2drbowen MapSource: An SQL SELECT statement that takes a single
0a3142725875ea286597e083547d34d98f8c1f2drbowen argument and returns a single value.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>This uses <module>mod_dbd</module> to implement a rewritemap
0a3142725875ea286597e083547d34d98f8c1f2drbowen by lookup in an SQL database. There are two forms:
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code>fastdbd</code> caches database lookups internally,
0a3142725875ea286597e083547d34d98f8c1f2drbowen <code>dbd</code> doesn't. So <code>dbd</code> incurs a
0a3142725875ea286597e083547d34d98f8c1f2drbowen performance penalty but responds immediately if the database
0a3142725875ea286597e083547d34d98f8c1f2drbowen contents are updated, while <code>fastdbd</code> is more
0a3142725875ea286597e083547d34d98f8c1f2drbowen efficient but won't re-read database contents until server
0a3142725875ea286597e083547d34d98f8c1f2drbowen restart.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>If a query returns more than one row, a random row from
0a3142725875ea286597e083547d34d98f8c1f2drbowen the result set is used.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
0a3142725875ea286597e083547d34d98f8c1f2drbowen <p>The <directive>RewriteMap</directive> directive can occur more than
0a3142725875ea286597e083547d34d98f8c1f2drbowen once. For each mapping-function use one
0a3142725875ea286597e083547d34d98f8c1f2drbowen <directive>RewriteMap</directive> 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>
0a3142725875ea286597e083547d34d98f8c1f2drbowen<note><title>Note</title> 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</manualpage>