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

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Using RewriteMap - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.5</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>Using RewriteMap</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
  22 </div>
  23
  24
  25     <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
  26 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
  27 the use of the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
  28 and provides examples of each of the various <code>RewriteMap</code> types.</p>
  29
  30     <div class="warning">Note that many of these examples won't work unchanged in your
  31 particular server configuration, so it's important that you understand
  32 them, rather than merely cutting and pasting the examples into your
  33 configuration.</div>
  34
  35   </div>
  36 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
  39 <li><img alt="" src="../images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
  40 <li><img alt="" src="../images/down.gif" /> <a href="#int">int: Internal Function</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
  42 <li><img alt="" src="../images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#summary">Summary</a></li>
  44 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li></ul></div>
  45 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  46 <div class="section">
  47 <h2><a name="introduction" id="introduction">Introduction</a></h2>
  48
  49
  50    <p>
  51    The <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive
  52    defines an external function which can be called in the context of
  53    <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or
  54    <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directives to
  55    perform rewriting that is too complicated, or too specialized to be
  56    performed just by regular expressions. The source of this lookup can
  57    be any of the types listed in the sections below, and enumerated in
  58    the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> reference
  59    documentation.</p>
  60
  61    <p>The syntax of the <code>RewriteMap</code> directive is as
  62    follows:</p>
  63
  64 <div class="example"><p><code>
  65 RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
  66 </code></p></div>
  67
  68     <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
  69     arbitray name that you assign to the map, and which you will use in
  70     directives later on. Arguments are passed to the map via the
  71     following syntax:</p>
  72
  73     <p class="indent">
  74       <strong>
  75         <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
  76         <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
  77         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
  78       </strong>
  79     </p>
  80
  81     <p>When such a construct occurs, the map <em>MapName</em> is
  82       consulted and the key <em>LookupKey</em> is looked-up. If the
  83       key is found, the map-function construct is substituted by
  84       <em>SubstValue</em>. If the key is not found then it is
  85       substituted by <em>DefaultValue</em> or by the empty string
  86       if no <em>DefaultValue</em> was specified.</p>
  87
  88     <p>For example, you might define a
  89       <code class="directive">RewriteMap</code> as:</p>
  90     <div class="example"><p><code>
  91       RewriteMap examplemap txt:/path/to/file/map.txt
  92       </code></p></div>
  93     <p>You would then be able to use this map in a
  94       <code class="directive">RewriteRule</code> as follows:</p>
  95 <div class="example"><p><code>
  96   RewriteRule ^/ex/(.*) ${examplemap:$1}
  97 </code></p></div>
  98
  99 <p>A default value can be specified in the event that nothing is found
 100 in the map:</p>
 101
 102 <div class="example"><p><code>
 103 RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}
 104 </code></p></div>
 105
 106 <div class="note"><h3>Per-directory and .htaccess context</h3>
 107 <p>
 108 The <code>RewriteMap</code> directive  may not be used in
 109 &lt;Directory&gt; sections or <code>.htaccess</code> files. You must
 110 declare the map in server or virtualhost context. You may use the map,
 111 once created, in your <code>RewriteRule</code> and
 112 <code>RewriteCond</code> directives in those scopes. You just can't
 113 <strong>declare</strong> it in those scopes.
 114 </p>
 115 </div>
 116
 117 <p>The sections that follow describe the various <em>MapType</em>s that
 118 may be used, and give examples of each.</p>
 119   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 120 <div class="section">
 121 <h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
 122
 123
 124     <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
 125     plain-text mapping file, containing space-separated key/value pair
 126     per line. Optionally, a line may be contain a comment, starting with
 127     a '#' character.</p>
 128
 129     <p>For example, the following might be valid entries in a map
 130     file.</p>
 131
 132     <p class="indent">
 133       # Comment line<br />
 134       <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
 135       <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
 136     </p>
 137
 138     <p>When the RewriteMap is invoked the argument is looked for in the
 139     first argument of a line, and, if found, the substitution value is
 140     returned.</p>
 141
 142     <p>For example, we might use a mapfile to translate product names to
 143     product IDs for easier-to-remember URLs, using the following
 144     recipe:</p>
 145
 146     <div class="example"><h3>Product to ID configuration</h3><p><code>
 147     RewriteMap product2id txt:/etc/apache2/productmap.txt<br />
 148     RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
 149     </code></p></div>
 150
 151     <p>We assume here that the <code>prods.php</code> script knows what
 152     to do when it received an argument of <code>id=NOTFOUND</code> when
 153     a product is not found in the lookup map.</p>
 154
 155     <p>The file <code>/etc/apache2/productmap.txt</code> then contains
 156     the following:</p>
 157
 158     <div class="example"><h3>Product to ID map</h3><p><code>
 159 ##<br />
 160 ##  productmap.txt - Product to ID map file<br />
 161 ##<br />
 162 <br />
 163 television 993<br />
 164 stereo     198<br />
 165 fishingrod 043<br />
 166 basketball 418<br />
 167 telephone  328
 168     </code></p></div>
 169
 170     <p>Thus, when <code>http://example.com/product/television</code> is
 171     requested, the <code>RewriteRule</code> is applied, and the request
 172     is internally mapped to <code>/prods.php?id=993</code>.</p>
 173
 174     <div class="note"><h3>Note: .htaccess files</h3>
 175     The example given is crafted to be used in server or virtualhost
 176     scope. If you're planning to use this in a <code>.htaccess</code>
 177     file, you'll need to remove the leading slash from the rewrite
 178     pattern in order for it to match anything:
 179     <div class="example"><p><code>
 180     RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
 181     </code></p></div>
 182     </div>
 183
 184     <div class="note"><h3>Cached lookups</h3>
 185     <p>
 186     The looked-up keys are cached by httpd until the <code>mtime</code>
 187     (modified time) of the mapfile changes, or the httpd server is
 188     restarted. This ensures better performance on maps that are called
 189     by many requests.
 190     </p>
 191     </div>
 192
 193   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 194 <div class="section">
 195 <h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
 196
 197
 198     <p>When a MapType of <code>rnd</code> is used, the MapSource is a
 199     filesystem path to a plain-text mapping file, each line of which
 200     contains a key, and one or more values separated by <code>|</code>.
 201     One of these values will be chosen at random if the key is
 202     matched.</p>
 203
 204     <p>For example, you might use the following map
 205     file and directives to provide a random load balancing between
 206     several back-end servers, via a reverse-proxy. Images are sent
 207     to one of the servers in the 'static' pool, while everything
 208     else is sent to one of the 'dynamic' pool.</p>
 209
 210     <div class="example"><h3>Rewrite map file</h3><p><code>
 211 ##<br />
 212 ##  map.txt -- rewriting map<br />
 213 ##<br />
 214 <br />
 215 static   www1|www2|www3|www4<br />
 216 dynamic  www5|www6
 217     </code></p></div>
 218
 219     <div class="example"><h3>Configuration directives</h3><p><code>
 220     RewriteMap servers rnd:/path/to/file/map.txt<br />
 221     <br />
 222     RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br />
 223     RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
 224     </code></p></div>
 225
 226     <p>So, when an image is requested and the first of these rules is
 227     matched, <code>RewriteMap</code> looks up the string
 228     <code>static</code> in the map file, which returns one of the
 229     specified hostnames at random, which is then used in the
 230     <code>RewriteRule</code> target.</p>
 231
 232     <p>If you wanted to have one of the servers more likely to be chosen
 233     (for example, if one of the server has more memory than the others,
 234     and so can handle more requests) simply list it more times in the
 235     map file.</p>
 236
 237     <div class="example"><p><code>
 238 static   www1|www1|www2|www3|www4
 239     </code></p></div>
 240
 241   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 242 <div class="section">
 243 <h2><a name="dbm" id="dbm">dbm: DBM Hash File</a></h2>
 244
 245
 246     <p>When a MapType of <code>dbm</code> is used, the MapSource is a
 247     filesystem path to a DBM database file containing key/value pairs to
 248     be used in the mapping. This works exactly the same way as the
 249     <code>txt</code> map, but is much faster, because a DBM is indexed,
 250     whereas a text file is not. This allows more rapid access to the
 251     desired key.</p>
 252
 253     <p>You may optionally specify a particular dbm type:</p>
 254
 255  <div class="example"><p><code>
 256  RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
 257  </code></p></div>
 258
 259     <p>The type can be sdbm, gdbm, ndbm or db.
 260     However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
 261     provided with Apache HTTP Server, as it will use the correct DBM library,
 262     matching the one that was used when httpd itself was built.</p>
 263
 264     <p>To create a dbm file, first create a text map file as described
 265     in the <a href="#txt">txt</a> section. Then run
 266     <code>httxt2dbm</code>:</p>
 267
 268 <div class="example"><p><code>
 269 $ httxt2dbm -i mapfile.txt -o mapfile.map
 270 </code></p></div>
 271
 272 <p>You can then reference the resulting file in your
 273 <code>RewriteMap</code> directive:</p>
 274
 275 <div class="example"><p><code>
 276 RewriteMap mapname dbm:/etc/apache/mapfile.map
 277 </code></p></div>
 278
 279 <div class="note">
 280 <p>Note that with some dbm types, more than one file is generated, with
 281 a common base name. For example, you may have two files named
 282 <code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
 283 normal, and you need only use the base name <code>mapfile.map</code> in
 284 your <code>RewriteMap</code> directive.</p>
 285 </div>
 286
 287 <div class="note"><h3>Cached lookups</h3>
 288 <p>
 289 The looked-up keys are cached by httpd until the <code>mtime</code>
 290 (modified time) of the mapfile changes, or the httpd server is
 291 restarted. This ensures better performance on maps that are called
 292 by many requests.
 293 </p>
 294 </div>
 295
 296   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 297 <div class="section">
 298 <h2><a name="int" id="int">int: Internal Function</a></h2>
 299
 300
 301     <p>When a MapType of <code>int</code> is used, the MapSource is one
 302     of the available internal RewriteMap functions.  Module authors can provide
 303     additional internal functions by registering them with the
 304     <code>ap_register_rewrite_mapfunc</code> API.
 305     The functions that are provided by default are:
 306     </p>
 307
 308     <ul>
 309       <li><strong>toupper</strong>:<br />
 310              Converts the key to all upper case.</li>
 311       <li><strong>tolower</strong>:<br />
 312              Converts the key to all lower case.</li>
 313       <li><strong>escape</strong>:<br />
 314              Translates special characters in the key to
 315             hex-encodings.</li>
 316       <li><strong>unescape</strong>:<br />
 317              Translates hex-encodings in the key back to
 318             special characters.</li>
 319     </ul>
 320
 321     <p>
 322     To use one of these functions, create a <code>RewriteMap</code> referencing
 323     the int function, and then use that in your <code>RewriteRule</code>:
 324     </p>
 325
 326     <div class="example"><h3>Redirect a URI to an all-lowercase version of itself</h3><p><code>
 327     RewriteMap lc int:tolower<br />
 328     RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
 329     </code></p></div>
 330
 331     <div class="note">
 332     <p>Please note that the example offered here is for
 333     illustration purposes only, and is not a recommendation. If you want
 334     to make URLs case-insensitive, consider using
 335     <code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code> instead.
 336     </p>
 337     </div>
 338
 339   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 340 <div class="section">
 341 <h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
 342
 343     <p>When a MapType of <code>prg</code> is used, the MapSource is a
 344     filesystem path to an executable program which will providing the
 345     mapping behavior. This can be a compiled binary file, or a program
 346     in an interpreted language such as Perl or Python.</p>
 347
 348     <p>This program is started once, when the Apache HTTP Server is
 349     started, and then communicates with the rewriting engine via
 350     <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
 351     function lookup, it expects one argument via <code>STDIN</code>, and
 352     should return one new-line terminated response string on
 353     <code>STDOUT</code>. If there is no corresponding lookup value, the
 354     map program should return the four-character string
 355     "<code>NULL</code>" to indicate this.</p>
 356
 357     <p>External rewriting programs are not started if they're defined in
 358     a context that does not have <code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
 359     <code>on</code>.</p>
 360
 361     <p>This feature utilizes the <code>rewrite-map</code> mutex,
 362     which is required for reliable communication with the program.
 363     The mutex mechanism and lock file can be configured with the
 364     <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
 365
 366     <p>A simple example is shown here which will replace all dashes with
 367     underscores in a request URI.</p>
 368
 369     <div class="example"><h3>Rewrite configuration</h3><p><code>
 370     RewriteMap d2u prg:/www/bin/dash2under.pl<br />
 371     RewriteRule - ${d2u:%{REQUEST_URI}}
 372     </code></p></div>
 373
 374     <div class="example"><h3>dash2under.pl</h3><p><code>
 375     #!/usr/bin/perl<br />
 376     $| = 1; # Turn off I/O buffering<br />
 377     while (&lt;STDIN&gt;) {<br />
 378         <span class="indent">
 379         s/-/_/g; # Replace dashes with underscores<br />
 380         print $_;<br />
 381         </span>
 382     }<br />
 383     </code></p></div>
 384
 385 <div class="note"><h3>Caution!</h3>
 386 <ul>
 387 <li>Keep your rewrite map program as simple as possible. If the program
 388 hangs, it will cause httpd to wait indefinitely for a response from the
 389 map, which will, in turn, cause httpd to stop responding to
 390 requests.</li>
 391 <li>Be sure to turn off buffering in your program. In Perl this is done
 392 by the second line in the example script: <code>$| = 1;</code> This will
 393 of course vary in other languages. Buffered I/O will cause httpd to wait
 394 for the output, and so it will hang.</li>
 395 <li>Remember that there is only one copy of the program, started at
 396 server startup. All requests will need to go through this one bottleneck.
 397 This can cause significant slowdowns if many requests must go through
 398 this process, or if the script itself is very slow.</li>
 399 </ul>
 400 </div>
 401
 402 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 403 <div class="section">
 404 <h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
 405
 406
 407     <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
 408     used, the MapSource is a SQL SELECT statement that takes a single
 409     argument and returns a single value.</p>
 410
 411     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
 412     the right database for this statement to be executed.</p>
 413
 414     <p>There are two forms of this MapType.
 415     Using a MapType of <code>dbd</code> causes the query to be
 416     executed with each map request, while using <code>fastdbd</code>
 417     caches the database lookups internally. So, while
 418     <code>fastdbd</code> is more efficient, and therefore faster, it
 419     won't pick up on changes to the database until the server is
 420     restarted.</p>
 421
 422     <p>If a query returns more than one row, a random row from
 423 the result set is used.</p>
 424
 425     <div class="example"><h3>Example</h3><p><code>
 426 RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
 427     </code></p></div>
 428
 429   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 430 <div class="section">
 431 <h2><a name="summary" id="summary">Summary</a></h2>
 432
 433
 434     <p>The <code class="directive">RewriteMap</code> directive can occur more than
 435     once. For each mapping-function use one
 436     <code class="directive">RewriteMap</code> directive to declare its rewriting
 437     mapfile.</p>
 438
 439     <p>While you cannot <strong>declare</strong> a map in
 440     per-directory context (<code>.htaccess</code> files or
 441     &lt;Directory&gt; blocks) it is possible to
 442     <strong>use</strong> this map in per-directory context. </p>
 443
 444   </div></div>
 445 <div class="bottomlang">
 446 <p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
 447 </div><div id="footer">
 448 <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 449 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 450 </body></html>