]> granicus.if.org Git - apache/blob - docs/manual/rewrite/rewritemap.html.en
rebuild
[apache] / 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 <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.4</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" /></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.4</p>
21 <img alt="" src="../images/feather.png" /></div>
22 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
23 <div id="path">
24 <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>
25 <div class="toplang">
26 <p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a> |
27 <a href="../fr/rewrite/rewritemap.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
28 </div>
29
30
31     <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
32 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
33 the use of the <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></code> directive,
34 and provides examples of each of the various <code>RewriteMap</code> types.</p>
35
36     <div class="warning">Note that many of these examples won't work unchanged in your
37 particular server configuration, so it's important that you understand
38 them, rather than merely cutting and pasting the examples into your
39 configuration.</div>
40
41   </div>
42 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
43 <li><img alt="" src="../images/down.gif" /> <a href="#txt">txt: Plain text maps</a></li>
44 <li><img alt="" src="../images/down.gif" /> <a href="#rnd">rnd: Randomized Plain Text</a></li>
45 <li><img alt="" src="../images/down.gif" /> <a href="#dbm">dbm: DBM Hash File</a></li>
46 <li><img alt="" src="../images/down.gif" /> <a href="#int">int: Internal Function</a></li>
47 <li><img alt="" src="../images/down.gif" /> <a href="#prg">prg: External Rewriting Program</a></li>
48 <li><img alt="" src="../images/down.gif" /> <a href="#dbd">dbd or fastdbd: SQL Query</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</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 <pre class="prettyprint lang-config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
71 </pre>
72
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     <pre class="prettyprint lang-config">RewriteMap examplemap "txt:/path/to/file/map.txt"</pre>
97
98     <p>You would then be able to use this map in a
99       <code class="directive">RewriteRule</code> as follows:</p>
100 <pre class="prettyprint lang-config">RewriteRule "^/ex/(.*)" "${examplemap:$1}"</pre>
101
102
103 <p>A default value can be specified in the event that nothing is found
104 in the map:</p>
105
106 <pre class="prettyprint lang-config">RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"</pre>
107
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 <p><strong>Product to ID configuration</strong></p>
149     <pre class="prettyprint lang-config">RewriteMap product2id "txt:/etc/apache2/productmap.txt"
150 RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]</pre>
151
152
153     <p>We assume here that the <code>prods.php</code> script knows what
154     to do when it received an argument of <code>id=NOTFOUND</code> when
155     a product is not found in the lookup map.</p>
156
157     <p>The file <code>/etc/apache2/productmap.txt</code> then contains
158     the following:</p>
159
160     <div class="example"><h3>Product to ID map</h3><p><code>
161 ##<br />
162 ##  productmap.txt - Product to ID map file<br />
163 ##<br />
164 <br />
165 television 993<br />
166 stereo     198<br />
167 fishingrod 043<br />
168 basketball 418<br />
169 telephone  328
170     </code></p></div>
171
172     <p>Thus, when <code>http://example.com/product/television</code> is
173     requested, the <code>RewriteRule</code> is applied, and the request
174     is internally mapped to <code>/prods.php?id=993</code>.</p>
175
176     <div class="note"><h3>Note: .htaccess files</h3>
177     The example given is crafted to be used in server or virtualhost
178     scope. If you're planning to use this in a <code>.htaccess</code>
179     file, you'll need to remove the leading slash from the rewrite
180     pattern in order for it to match anything:
181     <pre class="prettyprint lang-config">RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]</pre>
182
183     </div>
184
185     <div class="note"><h3>Cached lookups</h3>
186     <p>
187     The looked-up keys are cached by httpd until the <code>mtime</code>
188     (modified time) of the mapfile changes, or the httpd server is
189     restarted. This ensures better performance on maps that are called
190     by many requests.
191     </p>
192     </div>
193
194   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
195 <div class="section">
196 <h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
197     
198
199     <p>When a MapType of <code>rnd</code> is used, the MapSource is a
200     filesystem path to a plain-text mapping file, each line of which
201     contains a key, and one or more values separated by <code>|</code>.
202     One of these values will be chosen at random if the key is
203     matched.</p>
204
205     <p>For example, you might use the following map
206     file and directives to provide a random load balancing between
207     several back-end servers, via a reverse-proxy. Images are sent
208     to one of the servers in the 'static' pool, while everything
209     else is sent to one of the 'dynamic' pool.</p>
210
211     <div class="example"><h3>Rewrite map file</h3><p><code>
212 ##<br />
213 ##  map.txt -- rewriting map<br />
214 ##<br />
215 <br />
216 static   www1|www2|www3|www4<br />
217 dynamic  www5|www6
218     </code></p></div>
219 <p><strong>Configuration directives</strong></p>
220     <pre class="prettyprint lang-config">RewriteMap servers "rnd:/path/to/file/map.txt"
221
222 RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
223 RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]</pre>
224
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  <pre class="prettyprint lang-config">RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"</pre>
256
257
258     <p>The type can be sdbm, gdbm, ndbm or db.
259     However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
260     provided with Apache HTTP Server, as it will use the correct DBM library,
261     matching the one that was used when httpd itself was built.</p>
262
263     <p>To create a dbm file, first create a text map file as described
264     in the <a href="#txt">txt</a> section. Then run
265     <code>httxt2dbm</code>:</p>
266
267 <div class="example"><p><code>
268 $ httxt2dbm -i mapfile.txt -o mapfile.map
269 </code></p></div>
270
271 <p>You can then reference the resulting file in your
272 <code>RewriteMap</code> directive:</p>
273
274 <pre class="prettyprint lang-config">RewriteMap mapname "dbm:/etc/apache/mapfile.map"</pre>
275
276
277 <div class="note">
278 <p>Note that with some dbm types, more than one file is generated, with
279 a common base name. For example, you may have two files named
280 <code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
281 normal, and you need only use the base name <code>mapfile.map</code> in
282 your <code>RewriteMap</code> directive.</p>
283 </div>
284
285 <div class="note"><h3>Cached lookups</h3>
286 <p>
287 The looked-up keys are cached by httpd until the <code>mtime</code>
288 (modified time) of the mapfile changes, or the httpd server is
289 restarted. This ensures better performance on maps that are called
290 by many requests.
291 </p>
292 </div>
293
294   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
295 <div class="section">
296 <h2><a name="int" id="int">int: Internal Function</a></h2>
297     
298
299     <p>When a MapType of <code>int</code> is used, the MapSource is one
300     of the available internal RewriteMap functions.  Module authors can provide
301     additional internal functions by registering them with the
302     <code>ap_register_rewrite_mapfunc</code> API.
303     The functions that are provided by default are:
304     </p>
305
306     <ul>
307       <li><strong>toupper</strong>:<br />
308              Converts the key to all upper case.</li>
309       <li><strong>tolower</strong>:<br />
310              Converts the key to all lower case.</li>
311       <li><strong>escape</strong>:<br />
312              Translates special characters in the key to
313             hex-encodings.</li>
314       <li><strong>unescape</strong>:<br />
315              Translates hex-encodings in the key back to
316             special characters.</li>
317     </ul>
318
319     <p>
320     To use one of these functions, create a <code>RewriteMap</code> referencing
321     the int function, and then use that in your <code>RewriteRule</code>:
322     </p>
323
324    <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
325     <pre class="prettyprint lang-config">RewriteMap lc int:tolower
326 RewriteRule "(.*)" "${lc:$1}" [R]</pre>
327
328
329     <div class="note">
330     <p>Please note that the example offered here is for
331     illustration purposes only, and is not a recommendation. If you want
332     to make URLs case-insensitive, consider using
333     <code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code> instead.
334     </p>
335     </div>
336
337   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
338 <div class="section">
339 <h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
340
341     <p>When a MapType of <code>prg</code> is used, the MapSource is a
342     filesystem path to an executable program which will providing the
343     mapping behavior. This can be a compiled binary file, or a program
344     in an interpreted language such as Perl or Python.</p>
345
346     <p>This program is started once, when the Apache HTTP Server is
347     started, and then communicates with the rewriting engine via
348     <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
349     function lookup, it expects one argument via <code>STDIN</code>, and
350     should return one new-line terminated response string on
351     <code>STDOUT</code>. If there is no corresponding lookup value, the
352     map program should return the four-character string
353     "<code>NULL</code>" to indicate this.</p>
354
355     <p>External rewriting programs are not started if they're defined in
356     a context that does not have <code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
357     <code>on</code>.</p>
358
359     <p>This feature utilizes the <code>rewrite-map</code> mutex,
360     which is required for reliable communication with the program.
361     The mutex mechanism and lock file can be configured with the
362     <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
363
364     <p>A simple example is shown here which will replace all dashes with
365     underscores in a request URI.</p>
366     
367 <p><strong>Rewrite configuration</strong></p>
368     <pre class="prettyprint lang-config">RewriteMap d2u "prg:/www/bin/dash2under.pl"<br />
369 RewriteRule "-" "${d2u:%{REQUEST_URI}}"</pre>
370
371
372     <p><strong>dash2under.pl</strong></p>
373     <pre class="prettyprint lang-perl">#!/usr/bin/perl
374 $| = 1; # Turn off I/O buffering
375 while (&lt;STDIN&gt;) {
376     s/-/_/g; # Replace dashes with underscores
377     print $_;
378 }</pre>
379
380
381 <div class="note"><h3>Caution!</h3>
382 <ul>
383 <li>Keep your rewrite map program as simple as possible. If the program
384 hangs, it will cause httpd to wait indefinitely for a response from the
385 map, which will, in turn, cause httpd to stop responding to
386 requests.</li>
387 <li>Be sure to turn off buffering in your program. In Perl this is done
388 by the second line in the example script: <code>$| = 1;</code> This will
389 of course vary in other languages. Buffered I/O will cause httpd to wait
390 for the output, and so it will hang.</li>
391 <li>Remember that there is only one copy of the program, started at
392 server startup. All requests will need to go through this one bottleneck.
393 This can cause significant slowdowns if many requests must go through
394 this process, or if the script itself is very slow.</li>
395 </ul>
396 </div>
397
398 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
399 <div class="section">
400 <h2><a name="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
401     
402
403     <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
404     used, the MapSource is a SQL SELECT statement that takes a single
405     argument and returns a single value.</p>
406
407     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
408     the right database for this statement to be executed.</p>
409
410     <p>There are two forms of this MapType.
411     Using a MapType of <code>dbd</code> causes the query to be
412     executed with each map request, while using <code>fastdbd</code>
413     caches the database lookups internally. So, while
414     <code>fastdbd</code> is more efficient, and therefore faster, it
415     won't pick up on changes to the database until the server is
416     restarted.</p>
417
418     <p>If a query returns more than one row, a random row from
419 the result set is used.</p>
420
421         <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"</pre>
422 </div>
423
424   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
425 <div class="section">
426 <h2><a name="summary" id="summary">Summary</a></h2>
427     
428
429     <p>The <code class="directive">RewriteMap</code> directive can occur more than
430     once. For each mapping-function use one
431     <code class="directive">RewriteMap</code> directive to declare its rewriting
432     mapfile.</p>
433
434     <p>While you cannot <strong>declare</strong> a map in
435     per-directory context (<code>.htaccess</code> files or
436     &lt;Directory&gt; blocks) it is possible to
437     <strong>use</strong> this map in per-directory context. </p>
438
439   </div></div>
440 <div class="bottomlang">
441 <p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a> |
442 <a href="../fr/rewrite/rewritemap.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
443 </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&amp;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>
444 <script type="text/javascript"><!--//--><![CDATA[//><!--
445 var comments_shortname = 'httpd';
446 var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/rewritemap.html';
447 (function(w, d) {
448     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
449         d.write('<div id="comments_thread"><\/div>');
450         var s = d.createElement('script');
451         s.type = 'text/javascript';
452         s.async = true;
453         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
454         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
455     }
456     else { 
457         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
458     }
459 })(window, document);
460 //--><!]]></script></div><div id="footer">
461 <p class="apache">Copyright 2016 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>
462 <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[//><!--
463 if (typeof(prettyPrint) !== 'undefined') {
464     prettyPrint();
465 }
466 //--><!]]></script>
467 </body></html>