docs/manual/rewrite/rewritemap.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->
<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->
<manualpage metafile="rewritemap.xml.meta">
  <parentdocument href="./">Rewrite</parentdocument>
  <title>Using RewriteMap</title>
  <summary>

    <p>This document supplements the <module>mod_rewrite</module> 
<a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
and provides examples of each of the various <code>RewriteMap</code> types.</p>

    <note type="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.</note>

  </summary>
  <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
  <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
  <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
  <seealso><a href="access.html">Controlling access</a></seealso>
  <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
  <seealso><a href="proxy.html">Proxying</a></seealso>
  <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
  <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>

  <section id="introduction">
    <title>Introduction</title>

   <p>
   The <directive module="mod_rewrite">RewriteMap</directive> directive
   defines an external function which can be called in the context of
   <directive module="mod_rewrite">RewriteRule</directive> or
   <directive module="mod_rewrite">RewriteCond</directive> 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 <directive module="mod_rewrite">RewriteMap</directive> reference
   documentation.</p>

   <p>The syntax of the <code>RewriteMap</code> directive is as
   follows:</p>

<example>
RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
</example>
    
    <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
      <directive>RewriteMap</directive> as:</p>
    <example>
      RewriteMap examplemap txt:/path/to/file/map.txt
      </example>
    <p>You would then be able to use this map in a
      <directive>RewriteRule</directive> as follows:</p>
<example>
  RewriteRule ^/ex/(.*) ${examplemap:$1}
</example>

<p>A default value can be specified in the event that nothing is found
in the map:</p>

<example>
RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
</example>

<note><title>Per-directory and .htaccess context</title>
<p>
The <code>RewriteMap</code> directive  may not be used in
&lt;Directory&gt; sections or <code>.htaccess</code> files. You must
declare the map in server or virtualhost context. You may use the map,
once created, in your <code>RewriteRule</code> and
<code>RewriteCond</code> directives in those scopes. You just can't
<strong>declare</strong> it in those scopes.
</p>
</note>

<p>The sections that follow describe the various <em>MapType</em>s that
may be used, and give examples of each.</p>
  </section>

  <section id="txt">
    <title>txt: Plain text maps</title>

    <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
    plain-text mapping file, containing space-separated key/value pair
    per line. Optionally, a line may be contain a comment, starting with
    a '#' character.</p>

    <p>For example, the following might be valid entries in a map
    file.</p>

    <p class="indent">
      # Comment line<br />
      <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
      <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
    </p>

    <p>When the RewriteMap is invoked the argument is looked for in the
    first argument of a line, and, if found, the substitution value is
    returned.</p>

    <p>For example, we might use a mapfile to translate product names to
    product IDs for easier-to-remember URLs, using the following
    recipe:</p>

    <example><title>Product to ID configuration</title>
    RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
    RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
    </example>

    <p>We assume here that the <code>prods.php</code> script knows what
    to do when it received an argument of <code>id=NOTFOUND</code> when
    a product is not found in the lookup map.</p>

    <p>The file <code>/etc/apache2/productmap.txt</code> then contains
    the following:</p>

    <example><title>Product to ID map</title>
##<br />
##  productmap.txt - Product to ID map file<br />
##<br />
<br />
television 993<br />
stereo     198<br />
fishingrod 043<br />
basketball 418<br />
telephone  328
    </example>

    <p>Thus, when <code>http://example.com/product/television</code> is
    requested, the <code>RewriteRule</code> is applied, and the request
    is internally mapped to <code>/prods.php?id=993</code>.</p>

    <note><title>Note: .htaccess files</title>
    The example given is crafted to be used in server or virtualhost
    scope. If you're planning to use this in a <code>.htaccess</code>
    file, you'll need to remove the leading slash from the rewrite
    pattern in order for it to match anything:
    <example>
    RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
    </example>
    </note>

    <note><title>Cached lookups</title>
    <p>
    The looked-up keys are cached by httpd until the <code>mtime</code>
    (modified time) of the mapfile changes, or the httpd server is
    restarted. This ensures better performance on maps that are called
    by many requests.
    </p>
    </note>

  </section>
  <section id="rnd">
    <title>rnd: Randomized Plain Text</title>

    <p>When a MapType of <code>rnd</code> is used, the MapSource is a
    filesystem path to a plain-text mapping file, each line of which
    contains a key, and one or more values separated by <code>|</code>.
    One of these values will be chosen at random if the key is
    matched.</p>

    <p>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>

    <example><title>Rewrite map file</title>
##<br />
##  map.txt -- rewriting map<br />
##<br />
<br />
static   www1|www2|www3|www4<br />
dynamic  www5|www6
    </example>

    <example><title>Configuration directives</title>
    RewriteMap servers rnd:/path/to/file/map.txt<br/>
    <br/>
    RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>
    RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
    </example>

    <p>So, when an image is requested and the first of these rules is
    matched, <code>RewriteMap</code> looks up the string
    <code>static</code> in the map file, which returns one of the
    specified hostnames at random, which is then used in the
    <code>RewriteRule</code> target.</p>

    <p>If you wanted to have one of the servers more likely to be chosen
    (for example, if one of the server has more memory than the others,
    and so can handle more requests) simply list it more times in the
    map file.</p>

    <example>
static   www1|www1|www2|www3|www4
    </example>

  </section>

  <section id="dbm">
    <title>dbm: DBM Hash File</title>

    <p>When a MapType of <code>dbm</code> is used, the MapSource is a
    filesystem path to a DBM database file containing key/value pairs to
    be used in the mapping. This works exactly the same way as the
    <code>txt</code> map, but is much faster, because a DBM is indexed,
    whereas a text file is not. This allows more rapid access to the
    desired key.</p>

    <p>You may optionally specify a particular dbm type:</p>

 <example>
 RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
 </example>

    <p>The type can be sdbm, gdbm, ndbm or db.
    However, it is recommended that you just use the <a
    href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
    provided with Apache HTTP Server, as it will use the correct DBM library,
    matching the one that was used when httpd itself was built.</p>

    <p>To create a dbm file, first create a text map file as described
    in the <a href="#txt">txt</a> section. Then run
    <code>httxt2dbm</code>:</p>

<example>
$ httxt2dbm -i mapfile.txt -o mapfile.map
</example>

<p>You can then reference the resulting file in your
<code>RewriteMap</code> directive:</p>

<example>
RewriteMap mapname dbm:/etc/apache/mapfile.map
</example>

<note>
<p>Note that with some dbm types, more than one file is generated, with
a common base name. For example, you may have two files named
<code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
normal, and you need only use the base name <code>mapfile.map</code> in
your <code>RewriteMap</code> directive.</p>
</note>

<note><title>Cached lookups</title>
<p>
The looked-up keys are cached by httpd until the <code>mtime</code>
(modified time) of the mapfile changes, or the httpd server is
restarted. This ensures better performance on maps that are called
by many requests.
</p>
</note>

  </section>

  <section id="int">
    <title>int: Internal Function</title>

    <p>When a MapType of <code>int</code> is used, the MapSource is one
    of the available internal RewriteMap functions.  Module authors can provide 
    additional internal functions by registering them with the
    <code>ap_register_rewrite_mapfunc</code> API. 
    The functions that are provided by default are:
    </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>

    <p>
    To use one of these functions, create a <code>RewriteMap</code> referencing
    the int function, and then use that in your <code>RewriteRule</code>:
    </p>

    <example><title>Redirect a URI to an all-lowercase version of itself</title>
    RewriteMap lc int:tolower<br />
    RewriteRule (.*[A-Z]+.*) ${lc:$1} [R]
    </example>

    <note>
    <p>Please note that the example offered here is for
    illustration purposes only, and is not a recommendation. If you want
    to make URLs case-insensitive, consider using
    <module>mod_speling</module> instead.
    </p>
    </note>

  </section>

  <section id="prg"><title>prg: External Rewriting Program</title>

    <p>When a MapType of <code>prg</code> is used, the MapSource is a
    filesystem path to an executable program which will providing the
    mapping behavior. This can be a compiled binary file, or a program
    in an interpreted language such as Perl or Python.</p>

    <p>This program is started once, when the Apache HTTP Server is
    started, and then communicates with the rewriting engine via
    <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
    function lookup, it expects one argument via <code>STDIN</code>, and
    should return one new-line terminated response string on
    <code>STDOUT</code>. If there is no corresponding lookup value, the
    map program should return the four-character string
    "<code>NULL</code>" to indicate this.</p>

    <p>External rewriting programs are not started if they're defined in
    a context that does not have <directive
    module="mod_rewrite">RewriteEngine</directive> set to
    <code>on</code>.</p>

    <p>A simple example is shown here which will replace all dashes with
    underscores in a request URI.</p>

    <example><title>Rewrite configuration</title>
    RewriteMap d2u prg:/www/bin/dash2under.pl<br />
    RewriteRule - ${d2u:%{REQUEST_URI}}
    </example>

    <example><title>dash2under.pl</title>
    #!/usr/bin/perl<br />
    $| = 1; # Turn off I/O buffering<br />
    while (&lt;STDIN&gt;) {<br />
        <indent>
        s/-/_/g; # Replace dashes with underscores<br />
        print $_;<br />
        </indent>
    }<br />
    </example>

<note><title>Use a RewriteLock!</title>
<p>When using a <code>prg:</code> RewriteMap, you should use a
<directive module="mod_rewrite">RewriteLock</directive>. Failure to do so
will result in an error message in the log file, and may result in a
race condition on concurrent requests.</p>
</note>

<note><title>Caution!</title>
<ul>
<li>Keep your rewrite map program as simple as possible. If the program
hangs, it will cause httpd to wait indefinitely for a response from the
map, which will, in turn, cause httpd to stop responding to
requests.</li>
<li>Be sure to turn off buffering in your program. In Perl this is done
by the second line in the example script: <code>$| = 1;</code> This will
of course vary in other languages. Buffered I/O will cause httpd to wait
for the output, and so it will hang.</li>
<li>Remember that there is only one copy of the program, started at
server startup. All requests will need to go through this one bottleneck.
This can cause significant slowdowns if many requests must go through
this process, or if the script itself is very slow.</li>
</ul>
</note>

</section>

  <section id="summary">
    <title>Summary</title>

    <p>The <directive>RewriteMap</directive> directive can occur more than
    once. For each mapping-function use one
    <directive>RewriteMap</directive> directive to declare its rewriting
    mapfile.</p>
      
    <p>While you cannot <strong>declare</strong> a map in
    per-directory context (<code>.htaccess</code> files or
    &lt;Directory&gt; blocks) it is possible to
    <strong>use</strong> this map in per-directory context. </p>

  </section>
</manualpage>