rewritemap.xml revision 5d01f40ffd657dd2ac567aacd93cabd162ddfa79
5e01956f3000408c2a2c5a08c8d0acf2c2a9d8eeGlenn Barry<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<!-- $LastChangedRevision$ -->
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Licensed to the Apache Software Foundation (ASF) under one or more
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb contributor license agreements. See the NOTICE file distributed with
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb this work for additional information regarding copyright ownership.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The ASF licenses this file to You under the Apache License, Version 2.0
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb (the "License"); you may not use this file except in compliance with
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb the License. You may obtain a copy of the License at
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Unless required by applicable law or agreed to in writing, software
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb distributed under the License is distributed on an "AS IS" BASIS,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb See the License for the specific language governing permissions and
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb limitations under the License.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>This document supplements the <module>mod_rewrite</module>
159d09a20817016f09b3ea28d1bdada4a336bb91Mark Phalan<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbthe use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtband provides examples of each of the various <code>RewriteMap</code> types.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <note type="warning">Note that many of these examples won't work unchanged in your
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbparticular server configuration, so it's important that you understand
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbthem, rather than merely cutting and pasting the examples into your
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbconfiguration.</note>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </summary>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="access.html">Controlling access</a></seealso>
159d09a20817016f09b3ea28d1bdada4a336bb91Mark Phalan <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="advanced.html">Advanced techniques</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The <directive module="mod_rewrite">RewriteMap</directive> directive
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb defines an external function which can be called in the context of
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <directive module="mod_rewrite">RewriteRule</directive> or
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <directive module="mod_rewrite">RewriteCond</directive> directives to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb perform rewriting that is too complicated, or too specialized to be
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb performed just by regular expressions. The source of this lookup can
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb be any of the types listed in the sections below, and enumerated in
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb the <directive module="mod_rewrite">RewriteMap</directive> reference
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb documentation.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>The syntax of the <code>RewriteMap</code> directive is as
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb follows:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb</highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb arbitray name that you assign to the map, and which you will use in
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb directives later on. Arguments are passed to the map via the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb following syntax:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When such a construct occurs, the map <em>MapName</em> is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb consulted and the key <em>LookupKey</em> is looked-up. If the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb key is found, the map-function construct is substituted by
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb substituted by <em>DefaultValue</em> or by the empty string
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>For example, you can define a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>You would then be able to use this map in a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^/ex/(.*)" "${examplemap:$1}"
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<p>A default value can be specified in the event that nothing is found
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbin the map:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb</highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<Directory> sections or <code>.htaccess</code> files. You must
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbdeclare the map in server or virtualhost context. You may use the map,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<code>RewriteCond</code> directives in those scopes. You just can't
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<p>The sections that follow describe the various <em>MapType</em>s that
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbmay be used, and give examples of each.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When a MapType of <code>int</code> is used, the MapSource is one
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb of the available internal RewriteMap functions. Module authors can provide
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb additional internal functions by registering them with the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The functions that are provided by default are:
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Converts the key to all upper case.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Converts the key to all lower case.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Translates special characters in the key to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb hex-encodings.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Translates hex-encodings in the key back to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb special characters.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb To use one of these functions, create a <code>RewriteMap</code> referencing
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb the int function, and then use that in your <code>RewriteRule</code>:
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteMap lc "int:tolower"
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "(.*?[A-Z]+.*)" "${lc:$1}" [R]
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>Please note that the example offered here is for
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb illustration purposes only, and is not a recommendation. If you want
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb to make URLs case-insensitive, consider using
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb plain-text mapping file, containing space-separated key/value pair
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb per line. Optionally, a line may be contain a comment, starting with
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb a '#' character.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>A valid text rewrite map file will have the following syntax:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb # Comment line<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </example>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When the RewriteMap is invoked the argument is looked for in the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb first argument of a line, and, if found, the substitution value is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb returned.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>For example, we can use a mapfile to translate product names to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb product IDs for easier-to-remember URLs, using the following
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb recipe:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>We assume here that the <code>prods.php</code> script knows what
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb to do when it received an argument of <code>id=NOTFOUND</code> when
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb a product is not found in the lookup map.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>The file <code>/etc/apache2/productmap.txt</code> then contains
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb the following:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbtelevision 993<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbstereo 198<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbfishingrod 043<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbbasketball 418<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbtelephone 328
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </example>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>Thus, when <code>http://example.com/product/television</code> is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb requested, the <code>RewriteRule</code> is applied, and the request
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb is internally mapped to <code>/prods.php?id=993</code>.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The example given is crafted to be used in server or virtualhost
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb scope. If you're planning to use this in a <code>.htaccess</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb file, you'll need to remove the leading slash from the rewrite
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb pattern in order for it to match anything:
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The looked-up keys are cached by httpd until the <code>mtime</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb (modified time) of the mapfile changes, or the httpd server is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb restarted. This ensures better performance on maps that are called
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb by many requests.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When a MapType of <code>rnd</code> is used, the MapSource is a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb filesystem path to a plain-text mapping file, each line of which
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb contains a key, and one or more values separated by <code>|</code>.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb One of these values will be chosen at random if the key is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb matched.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>For example, you can use the following map
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb file and directives to provide a random load balancing between
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb several back-end servers, via a reverse-proxy. Images are sent
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb to one of the servers in the 'static' pool, while everything
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb else is sent to one of the 'dynamic' pool.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbstatic www1|www2|www3|www4<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbdynamic www5|www6
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </example>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>So, when an image is requested and the first of these rules is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>static</code> in the map file, which returns one of the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb specified hostnames at random, which is then used in the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>If you wanted to have one of the servers more likely to be chosen
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb (for example, if one of the server has more memory than the others,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb and so can handle more requests) simply list it more times in the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb map file.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbstatic www1|www1|www2|www3|www4
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </example>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When a MapType of <code>dbm</code> is used, the MapSource is a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb filesystem path to a DBM database file containing key/value pairs to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb be used in the mapping. This works exactly the same way as the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>txt</code> map, but is much faster, because a DBM is indexed,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb whereas a text file is not. This allows more rapid access to the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb desired key.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>You may optionally specify a particular dbm type:</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>The type can be sdbm, gdbm, ndbm or db.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb However, it is recommended that you just use the <a
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb href="/programs/httxt2dbm.html">httxt2dbm</a> utility that is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb provided with Apache HTTP Server, as it will use the correct DBM library,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb matching the one that was used when httpd itself was built.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>To create a dbm file, first create a text map file as described
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<p>You can then reference the resulting file in your
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb</highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<p>Note that with some dbm types, more than one file is generated, with
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtba common base name. For example, you may have two files named
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbnormal, and you need only use the base name <code>mapfile.map</code> in
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbThe looked-up keys are cached by httpd until the <code>mtime</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb(modified time) of the mapfile changes, or the httpd server is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbrestarted. This ensures better performance on maps that are called
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbby many requests.
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry <section id="prg"><title>prg: External Rewriting Program</title>
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry <p>When a MapType of <code>prg</code> is used, the MapSource is a
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry filesystem path to an executable program which will providing the
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry mapping behavior. This can be a compiled binary file, or a program
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry in an interpreted language such as Perl or Python.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>This program is started once, when the Apache HTTP Server is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb started, and then communicates with the rewriting engine via
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb function lookup, it expects one argument via <code>STDIN</code>, and
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb should return one new-line terminated response string on
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>STDOUT</code>. If there is no corresponding lookup value, the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb map program should return the four-character string
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>External rewriting programs are not started if they're defined in
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb a context that does not have <directive
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>By default, external rewriting programs are run as the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb user:group who started httpd. This can be changed on UNIX systems
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb by passing user name and group name as third argument to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <directive module="mod_rewrite">RewriteMap</directive> in the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>This feature utilizes the <code>rewrite-map</code> mutex,
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb which is required for reliable communication with the program.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb The mutex mechanism and lock file can be configured with the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <directive module="core">Mutex</directive> directive.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>A simple example is shown here which will replace all dashes with
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb underscores in a request URI.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteMap d2u "prg:/www/bin/dash2under.programlisting" apache:apache<br />
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteRule "-" "${d2u:%{REQUEST_URI}}"
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb $| = 1; # Turn off I/O buffering
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb while (<STDIN>) {
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb s/-/_/g; # Replace dashes with underscores
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<li>Keep your rewrite map program as simple as possible. If the program
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbhangs, it will cause httpd to wait indefinitely for a response from the
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbmap, which will, in turn, cause httpd to stop responding to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbrequests.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<li>Be sure to turn off buffering in your program. In Perl this is done
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbby the second line in the example script: <code>$| = 1;</code> This will
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbof course vary in other languages. Buffered I/O will cause httpd to wait
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbfor the output, and so it will hang.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb<li>Remember that there is only one copy of the program, started at
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbserver startup. All requests will need to go through this one bottleneck.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbThis can cause significant slowdowns if many requests must go through
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbthis process, or if the script itself is very slow.</li>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb used, the MapSource is a SQL SELECT statement that takes a single
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb argument and returns a single value.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p><module>mod_dbd</module> will need to be configured to point at
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb the right database for this statement to be executed.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>There are two forms of this MapType.
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb Using a MapType of <code>dbd</code> causes the query to be
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb executed with each map request, while using <code>fastdbd</code>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb caches the database lookups internally. So, while
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <code>fastdbd</code> is more efficient, and therefore faster, it
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb won't pick up on changes to the database until the server is
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb restarted.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>If a query returns more than one row, a random row from
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbthe result set is used.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtbRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
ba7b222e36bac28710a7f43739283302b617e7f5Glenn Barry </highlight>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <p>The <directive>RewriteMap</directive> directive can occur more than
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb once. For each mapping-function use one
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <directive>RewriteMap</directive> directive to declare its rewriting
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb mapfile.</p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <Directory> blocks) it is possible to
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb <strong>use</strong> this map in per-directory context. </p>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb </section>
ab9b2e153c3a9a2b1141fefa87925b1a9beb1236gtb</manualpage>