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