granicus.if.org Git - apache/blob - docs/manual/rewrite/rewritemap.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision: 882992 $ -->
   5 <!--
   6  Licensed to the Apache Software Foundation (ASF) under one or more
   7  contributor license agreements.  See the NOTICE file distributed with
   8  this work for additional information regarding copyright ownership.
   9  The ASF licenses this file to You under the Apache License, Version 2.0
  10  (the "License"); you may not use this file except in compliance with
  11  the License.  You may obtain a copy of the License at
  12
  13      http://www.apache.org/licenses/LICENSE-2.0
  14
  15  Unless required by applicable law or agreed to in writing, software
  16  distributed under the License is distributed on an "AS IS" BASIS,
  17  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  See the License for the specific language governing permissions and
  19  limitations under the License.
  20 -->
  21 <manualpage metafile="rewritemap.xml.meta">
  22   <parentdocument href="./">Rewrite</parentdocument>
  23   <title>Using RewriteMap</title>
  24   <summary>
  25
  26     <p>This document supplements the <module>mod_rewrite</module>
  27 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
  28 the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
  29 and provides examples of each of the various <code>RewriteMap</code> types.</p>
  30
  31     <note type="warning">Note that many of these examples won't work unchanged in your
  32 particular server configuration, so it's important that you understand
  33 them, rather than merely cutting and pasting the examples into your
  34 configuration.</note>
  35
  36   </summary>
  37   <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
  38   <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
  39   <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
  40   <seealso><a href="access.html">Controlling access</a></seealso>
  41   <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
  42   <seealso><a href="proxy.html">Proxying</a></seealso>
  43   <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
  44   <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
  45
  46   <section id="introduction">
  47     <title>Introduction</title>
  48
  49    <p>
  50    The <directive module="mod_rewrite">RewriteMap</directive> directive
  51    defines an external function which can be called in the context of
  52    <directive module="mod_rewrite">RewriteRule</directive> or
  53    <directive module="mod_rewrite">RewriteCond</directive> directives to
  54    perform rewriting that is too complicated, or too specialized to be
  55    performed just by regular expressions. The source of this lookup can
  56    be any of the types listed in the sections below, and enumerated in
  57    the <directive module="mod_rewrite">RewriteMap</directive> reference
  58    documentation.</p>
  59
  60    <p>The syntax of the <code>RewriteMap</code> directive is as
  61    follows:</p>
  62
  63 <example>
  64 RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
  65 </example>
  66
  67     <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
  68     arbitray name that you assign to the map, and which you will use in
  69     directives later on. Arguments are passed to the map via the
  70     following syntax:</p>
  71
  72     <p class="indent">
  73       <strong>
  74         <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
  75         <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
  76         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
  77       </strong>
  78     </p>
  79
  80     <p>When such a construct occurs, the map <em>MapName</em> is
  81       consulted and the key <em>LookupKey</em> is looked-up. If the
  82       key is found, the map-function construct is substituted by
  83       <em>SubstValue</em>. If the key is not found then it is
  84       substituted by <em>DefaultValue</em> or by the empty string
  85       if no <em>DefaultValue</em> was specified.</p>
  86
  87     <p>For example, you might define a
  88       <directive>RewriteMap</directive> as:</p>
  89     <example>
  90       RewriteMap examplemap txt:/path/to/file/map.txt
  91       </example>
  92     <p>You would then be able to use this map in a
  93       <directive>RewriteRule</directive> as follows:</p>
  94     <example>
  95       RewriteRule ^/ex/(.*) ${examplemap:$1}
  96       </example>
  97
  98 <p>The sections that follow describe the various <em>MapType</em>s that
  99 may be used, and give examples of each.</p>
 100   </section>
 101
 102   <section id="txt">
 103     <title>txt: Plain text maps</title>
 104     <p>MapType: <code>txt</code>, MapSource: Unix filesystem
 105       path to valid regular file</p>
 106     <p>This is the standard rewriting map feature where the
 107       <em>MapSource</em> is a plain ASCII file containing
 108       either blank lines, comment lines (starting with a '#'
 109       character) or pairs like the following - one per
 110       line.</p>
 111     <p class="indent">
 112       <strong>
 113         <em>MatchingKey</em>
 114         <em>SubstValue</em>
 115       </strong>
 116     </p>
 117     <example>
 118       <title>Example</title>
 119       <pre>
 120 ##
 121 ##  map.txt -- rewriting map
 122 ##
 123
 124 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
 125 Mr.Joe.Average        joe   # Mr. Average
 126 </pre>
 127     </example>
 128     <example>
 129 RewriteMap real-to-user txt:/path/to/file/map.txt
 130 </example>
 131   </section>
 132   <section id="rnd">
 133     <title>rnd: Randomized Plain Text</title>
 134     <p>MapType: <code>rnd</code>, MapSource: Unix filesystem
 135           path to valid regular file</p>
 136     <p>This is identical to the Standard Plain Text variant
 137           above but with a special post-processing feature: After
 138           looking up a value it is parsed according to contained
 139           ``<code>|</code>'' characters which have the meaning of
 140           ``or''. In other words they indicate a set of
 141           alternatives from which the actual returned value is
 142           chosen randomly. For example, you might use the following map
 143           file and directives to provide a random load balancing between
 144           several back-end server, via a reverse-proxy. Images are sent
 145           to one of the servers in the 'static' pool, while everything
 146           else is sent to one of the 'dynamic' pool.</p>
 147     <p>Example:</p>
 148     <example>
 149       <title>Rewrite map file</title>
 150       <pre>
 151 ##
 152 ##  map.txt -- rewriting map
 153 ##
 154
 155 static   www1|www2|www3|www4
 156 dynamic  www5|www6
 157 </pre>
 158     </example>
 159     <example><title>Configuration directives</title>
 160 RewriteMap servers rnd:/path/to/file/map.txt<br/>
 161 <br/>
 162 RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
 163 [NC,P,L]<br/>
 164 RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
 165 </example>
 166   </section>
 167   <section id="dbm">
 168     <title>dbm: DBM Hash File</title>
 169     <p>MapType:
 170           <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
 171           path to valid regular file</p>
 172     <p>Here the source is a binary format DBM file containing
 173           the same contents as a <em>Plain Text</em> format file, but
 174           in a special representation which is optimized for really
 175           fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
 176           db depending on <a href="../install.html#dbm">compile-time
 177           settings</a>.  If the <em>type</em> is omitted, the
 178           compile-time default will be chosen.</p>
 179     <p>To create a dbm file from a source text file, use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
 180     <example>
 181 $ httxt2dbm -i mapfile.txt -o mapfile.map
 182 </example>
 183   </section>
 184   <section id="int">
 185     <title>int: Internal Function</title>
 186     <p>
 187            MapType: <code>int</code>, MapSource: Internal Apache httpd
 188           function</p>
 189     <p>Here, the source is an internal Apache httpd function.
 190           Currently you cannot create your own, but the following
 191           functions already exist:</p>
 192     <ul>
 193       <li><strong>toupper</strong>:<br/>
 194              Converts the key to all upper case.</li>
 195       <li><strong>tolower</strong>:<br/>
 196              Converts the key to all lower case.</li>
 197       <li><strong>escape</strong>:<br/>
 198              Translates special characters in the key to
 199             hex-encodings.</li>
 200       <li><strong>unescape</strong>:<br/>
 201              Translates hex-encodings in the key back to
 202             special characters.</li>
 203     </ul>
 204   </section>
 205   <section id="prg"><title>prg: External Rewriting Program</title>
 206
 207 <p>MapType: <code>prg</code>, MapSource: Unix filesystem path to valid regular file </p>
 208
 209 <p>Here the source is a program, not a map file. To
 210 create it you can use a language of your choice, but
 211 the result has to be an executable program (either
 212 object-code or a script with the magic cookie trick
 213 '<code>#!/path/to/interpreter</code>' as the first
 214 line).</p><p>This program is started once, when the Apache httpd server
 215 is started, and then communicates with the rewriting engine
 216 via its <code>stdin</code> and <code>stdout</code>
 217 file-handles. For each map-function lookup it will
 218 receive the key to lookup as a newline-terminated string
 219 on <code>stdin</code>. It then has to give back the
 220 looked-up value as a newline-terminated string on
 221 <code>stdout</code> or the four-character string
 222 ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
 223 is no corresponding value for the given key).</p><p>This feature utilizes the <code>rewrite-map</code> mutex,
 224 which is required for reliable communication with the program.
 225 The mutex mechanism and lock file can be configured with the
 226 <directive module="core">Mutex</directive> directive.</p><p>External rewriting programs are not started if they're defined in a
 227 context that does not have <directive>RewriteEngine</directive> set to
 228 <code>on</code></p>.
 229
 230           <p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,
 231           key == value) could be:</p><example><pre>
 232 #!/usr/bin/perl
 233 $| = 1;
 234 while (&lt;STDIN&gt;) {
 235     # ...put here any transformations or lookups...
 236     print $_;
 237 }
 238 </pre></example><p>But be very careful:</p><ol><li>``<em>Keep it simple, stupid</em>'' (KISS).
 239 If this program hangs, it will cause Apache httpd to hang
 240 when trying to use the relevant rewrite rule.</li><li>A common mistake is to use buffered I/O on
 241 <code>stdout</code>. Avoid this, as it will cause a deadloop!
 242 ``<code>$|=1</code>'' is used above, to prevent this.</li></ol></section>
 243   <section id="dbd">
 244     <title>dbd or fastdbd: SQL Query</title>
 245     <p>MapType: <code>dbd</code> or <code>fastdbd</code>,
 246 MapSource: An SQL SELECT statement that takes a single
 247           argument and returns a single value.</p>
 248     <p>This uses <module>mod_dbd</module> to implement a rewritemap
 249 by lookup in an SQL database.  There are two forms:
 250 <code>fastdbd</code> caches database lookups internally,
 251 <code>dbd</code> doesn't.  So <code>dbd</code> incurs a
 252 performance penalty but responds immediately if the database
 253 contents are updated, while <code>fastdbd</code> is more
 254 efficient but won't re-read database contents until server
 255 restart.</p>
 256     <p>If a query returns more than one row, a random row from
 257 the result set is used.</p>
 258     <example><title>Example</title>
 259 RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
 260 </example>
 261   </section>
 262   <section id="summary">
 263     <title>Summary</title>
 264     <p>The <directive>RewriteMap</directive> directive can occur more than
 265       once. For each mapping-function use one
 266       <directive>RewriteMap</directive> directive to declare its rewriting
 267       mapfile. While you cannot <strong>declare</strong> a map in
 268       per-directory context it is of course possible to
 269       <strong>use</strong> this map in per-directory context. </p>
 270     <note><title>Note</title> For plain text and DBM format files the
 271 looked-up keys are cached in-core until the <code>mtime</code> of the
 272 mapfile changes or the server does a restart. This way you can have
 273 map-functions in rules which are used for <strong>every</strong>
 274 request.  This is no problem, because the external lookup only happens
 275 once!
 276 </note>
 277   </section>
 278 </manualpage>