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