rewritemap.xml revision 53abc235688d883cfa15cdfec354ba03128f357a
0a3142725875ea286597e083547d34d98f8c1f2drbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
723d1cf47a33d814dc2d980473060e8faf4036a2nd<!-- $LastChangedRevision$ -->
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.
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <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>
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <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>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="access.html">Controlling access</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="advanced.html">Advanced techniques</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen The <directive module="mod_rewrite">RewriteMap</directive> directive
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen defines an external function which can be called in the context of
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <directive module="mod_rewrite">RewriteRule</directive> or
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <directive module="mod_rewrite">RewriteCond</directive> directives to
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen perform rewriting that is too complicated, or too specialized to be
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen performed just by regular expressions. The source of this lookup can
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen be any of the types listed in the sections below, and enumerated in
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen the <directive module="mod_rewrite">RewriteMap</directive> reference
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen documentation.</p>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <p>The syntax of the <code>RewriteMap</code> directive is as
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen follows:</p>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen arbitray name that you assign to the map, and which you will use in
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen directives later on. Arguments are passed to the map via the
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen following syntax:</p>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <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
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>For example, you might define a
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>You would then be able to use this map in a
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^/ex/(.*) ${examplemap:$1}
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen<p>A default value can be specified in the event that nothing is found
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenin the map:</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowenRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<note><title>Per-directory and .htaccess context</title>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThe <code>RewriteMap</code> directive may not be used in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<Directory> sections or <code>.htaccess</code> files. You must
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowendeclare the map in server or virtualhost context. You may use the map,
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<code>RewriteCond</code> directives in those scopes. You just can't
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen<p>The sections that follow describe the various <em>MapType</em>s that
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowenmay be used, and give examples of each.</p>
79a240bcddede9174bfb9e9ca9210e974347af77rbowen <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen plain-text mapping file, containing space-separated key/value pair
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen per line. Optionally, a line may be contain a comment, starting with
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen a '#' character.</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>For example, the following might be valid entries in a map
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen # Comment line<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>When the RewriteMap is invoked the argument is looked for in the
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen first argument of a line, and, if found, the substitution value is
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen returned.</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>For example, we might use a mapfile to translate product names to
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen product IDs for easier-to-remember URLs, using the following
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen recipe:</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>We assume here that the <code>prods.php</code> script knows what
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen to do when it received an argument of <code>id=NOTFOUND</code> when
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen a product is not found in the lookup map.</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>The file <code>/etc/apache2/productmap.txt</code> then contains
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen the following:</p>
2492b89218fc132ff9e006687c4aa514fe694f01rbowentelevision 993<br />
2492b89218fc132ff9e006687c4aa514fe694f01rbowenstereo 198<br />
2492b89218fc132ff9e006687c4aa514fe694f01rbowenfishingrod 043<br />
2492b89218fc132ff9e006687c4aa514fe694f01rbowenbasketball 418<br />
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowentelephone 328
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen <p>Thus, when <code>http://example.com/product/television</code> is
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen requested, the <code>RewriteRule</code> is applied, and the request
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen is internally mapped to <code>/prods.php?id=993</code>.</p>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen The example given is crafted to be used in server or virtualhost
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen scope. If you're planning to use this in a <code>.htaccess</code>
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen file, you'll need to remove the leading slash from the rewrite
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen pattern in order for it to match anything:
721755eb7ca9b3bf233f223d48e43edd7795c6ebrbowen RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen The looked-up keys are cached by httpd until the <code>mtime</code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen (modified time) of the mapfile changes, or the httpd server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen restarted. This ensures better performance on maps that are called
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen by many requests.
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>When a MapType of <code>rnd</code> is used, the MapSource is a
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen filesystem path to a plain-text mapping file, each line of which
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen contains a key, and one or more values separated by <code>|</code>.
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen One of these values will be chosen at random if the key is
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen matched.</p>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>For example, you might use the following map
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen file and directives to provide a random load balancing between
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen several back-end server, via a reverse-proxy. Images are sent
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen to one of the servers in the 'static' pool, while everything
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen else is sent to one of the 'dynamic' pool.</p>
2492b89218fc132ff9e006687c4aa514fe694f01rbowenstatic www1|www2|www3|www4<br />
0a3142725875ea286597e083547d34d98f8c1f2drbowendynamic www5|www6
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>So, when an image is requested and the first of these rules is
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <code>static</code> in the map file, which returns one of the
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen specified hostnames at random, which is then used in the
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen <p>If you wanted to have one of the servers more likely to be chosen
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen (for example, if one of the server has more memory than the others,
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen and so can handle more requests) simply list it more times in the
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowen map file.</p>
dcfbe1c582e8e138f6f36ac7c4eb4d3f1e241346rbowenstatic www1|www1|www2|www3|www4
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>When a MapType of <code>dbm</code> is used, the MapSource is a
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen filesystem path to a DBM database file containing key/value pairs to
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen be used in the mapping. This works exactly the same way as the
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <code>txt</code> map, but is much faster, because a DBM is indexed,
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen whereas a text file is not. This allows more rapid access to the
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen desired key.</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>You may optionally specify a particular dbm type:</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>The type can be sdbm, gdbm, ndbm or db.
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen However, it is recommended that you just use the <a
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen provided with Apache HTTP Server, as it will use the correct DBM library,
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen matching the one that was used when httpd itself was built.</p>
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen <p>To create a dbm file, first create a text map file as described
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<p>You can then reference the resulting file in your
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<p>Note that with some dbm types, more than one file is generated, with
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowena common base name. For example, you may have two files named
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowen<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
7897152e0fe2ecfb63ddad590e468fbf0b4419d7rbowennormal, and you need only use the base name <code>mapfile.map</code> in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThe looked-up keys are cached by httpd until the <code>mtime</code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen(modified time) of the mapfile changes, or the httpd server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenrestarted. This ensures better performance on maps that are called
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenby many requests.
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <p>When a MapType of <code>int</code> is used, the MapSource is one
cb2bc248359cade6518cf6c68394dc6865ba992ccovener of the available internal RewriteMap functions. Module authors can provide
9fa69be7454a9c2f1ef63321fd04eae825e48d79covener additional internal functions by registering them with the
cb2bc248359cade6518cf6c68394dc6865ba992ccovener The functions that are provided by default are:
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>
5c5ef751538ad31a6cef69f814996fe7453e383drbowen To use one of these functions, create a <code>RewriteMap</code> referencing
5c5ef751538ad31a6cef69f814996fe7453e383drbowen the int function, and then use that in your <code>RewriteRule</code>:
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <example><title>Redirect a URI to an all-lowercase version of itself</title>
5c5ef751538ad31a6cef69f814996fe7453e383drbowen RewriteMap lc int:tolower<br />
9245eb17c39fd97c99204c8f6fb426a9a6972fa7sf RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
5c5ef751538ad31a6cef69f814996fe7453e383drbowen <p>Please note that the example offered here is for
5c5ef751538ad31a6cef69f814996fe7453e383drbowen illustration purposes only, and is not a recommendation. If you want
5c5ef751538ad31a6cef69f814996fe7453e383drbowen to make URLs case-insensitive, consider using
83f3471f5de14ca3def6d7935cd1af1604874bfdrbowen <section id="prg"><title>prg: External Rewriting Program</title>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>When a MapType of <code>prg</code> is used, the MapSource is a
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen filesystem path to an executable program which will providing the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen mapping behavior. This can be a compiled binary file, or a program
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen in an interpreted language such as Perl or Python.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>This program is started once, when the Apache HTTP Server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen started, and then communicates with the rewriting engine via
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen function lookup, it expects one argument via <code>STDIN</code>, and
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen should return one new-line terminated response string on
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>STDOUT</code>. If there is no corresponding lookup value, the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen map program should return the four-character string
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>External rewriting programs are not started if they're defined in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen a context that does not have <directive
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen module="mod_rewrite">RewriteEngine</directive> set to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>This feature utilizes the <code>rewrite-map</code> mutex,
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen which is required for reliable communication with the program.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen The mutex mechanism and lock file can be configured with the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <directive module="core">Mutex</directive> directive.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>A simple example is shown here which will replace all dashes with
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen underscores in a request URI.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen RewriteRule - ${d2u:%{REQUEST_URI}}
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen $| = 1; # Turn off I/O buffering<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen while (<STDIN>) {<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen s/-/_/g; # Replace dashes with underscores<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen print $_;<br />
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Keep your rewrite map program as simple as possible. If the program
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenhangs, it will cause httpd to wait indefinitely for a response from the
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenmap, which will, in turn, cause httpd to stop responding to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenrequests.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Be sure to turn off buffering in your program. In Perl this is done
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenby the second line in the example script: <code>$| = 1;</code> This will
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenof course vary in other languages. Buffered I/O will cause httpd to wait
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenfor the output, and so it will hang.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen<li>Remember that there is only one copy of the program, started at
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenserver startup. All requests will need to go through this one bottleneck.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenThis can cause significant slowdowns if many requests must go through
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowenthis process, or if the script itself is very slow.</li>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen used, the MapSource is a SQL SELECT statement that takes a single
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen argument and returns a single value.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p><module>mod_dbd</module> will need to be configured to point at
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen the right database for this statement to be executed.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>There are two forms of this MapType.
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen Using a MapType of <code>dbd</code> causes the query to be
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen executed with each map request, while using <code>fastdbd</code>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen caches the database lookups internally. So, while
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <code>fastdbd</code> is more efficient, and therefore faster, it
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen won't pick up on changes to the database until the server is
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen restarted.</p>
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>If a query returns more than one row, a random row from
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowenthe result set is used.</p>
0a3142725875ea286597e083547d34d98f8c1f2drbowenRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen <p>The <directive>RewriteMap</directive> directive can occur more than
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen once. For each mapping-function use one
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <directive>RewriteMap</directive> directive to declare its rewriting
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen mapfile.</p>
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <p>While you cannot <strong>declare</strong> a map in
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen per-directory context (<code>.htaccess</code> files or
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <Directory> blocks) it is possible to
5583cc9f4d6d30122ee4c0bc47ebe1bd67dd80e6rbowen <strong>use</strong> this map in per-directory context. </p>
d0978b1d74a5614cfc225aa772fe90344bf85d0drbowen</manualpage>