]> granicus.if.org Git - apache/blob - docs/manual/rewrite/rewritemap.html.en
xforms
[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         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.5</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.5</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><ul class="seealso"><li><a href="#comments_section">Comments</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 <pre class="prettyprint lang-config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></pre>
68
69
70     <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
71     arbitray name that you assign to the map, and which you will use in
72     directives later on. Arguments are passed to the map via the
73     following syntax:</p>
74
75     <p class="indent">
76       <strong>
77         <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
78         <code>}</code> <br /> <code>${</code> <em>MapName</em> <code>:</code>
79         <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
80       </strong>
81     </p>
82
83     <p>When such a construct occurs, the map <em>MapName</em> is
84       consulted and the key <em>LookupKey</em> is looked-up. If the
85       key is found, the map-function construct is substituted by
86       <em>SubstValue</em>. If the key is not found then it is
87       substituted by <em>DefaultValue</em> or by the empty string
88       if no <em>DefaultValue</em> was specified.</p>
89
90     <p>For example, you might define a
91       <code class="directive">RewriteMap</code> as:</p>
92     <pre class="prettyprint lang-config">RewriteMap examplemap txt:/path/to/file/map.txt</pre>
93
94     <p>You would then be able to use this map in a
95       <code class="directive">RewriteRule</code> as follows:</p>
96 <pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1}</pre>
97
98
99 <p>A default value can be specified in the event that nothing is found
100 in the map:</p>
101
102 <pre class="prettyprint lang-config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</pre>
103
104
105 <div class="note"><h3>Per-directory and .htaccess context</h3>
106 <p>
107 The <code>RewriteMap</code> directive  may not be used in
108 &lt;Directory&gt; sections or <code>.htaccess</code> files. You must
109 declare the map in server or virtualhost context. You may use the map,
110 once created, in your <code>RewriteRule</code> and
111 <code>RewriteCond</code> directives in those scopes. You just can't
112 <strong>declare</strong> it in those scopes.
113 </p>
114 </div>
115
116 <p>The sections that follow describe the various <em>MapType</em>s that
117 may be used, and give examples of each.</p>
118   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
119 <div class="section">
120 <h2><a name="txt" id="txt">txt: Plain text maps</a></h2>
121     
122
123     <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
124     plain-text mapping file, containing space-separated key/value pair
125     per line. Optionally, a line may be contain a comment, starting with
126     a '#' character.</p>
127
128     <p>For example, the following might be valid entries in a map
129     file.</p>
130
131     <p class="indent">
132       # Comment line<br />
133       <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
134       <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
135     </p>
136
137     <p>When the RewriteMap is invoked the argument is looked for in the
138     first argument of a line, and, if found, the substitution value is
139     returned.</p>
140
141     <p>For example, we might use a mapfile to translate product names to
142     product IDs for easier-to-remember URLs, using the following
143     recipe:</p>
144 <p><strong>Product to ID configuration</strong></p>
145     <pre class="prettyprint lang-config">
146 RewriteMap product2id txt:/etc/apache2/productmap.txt
147 RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
148     </pre>
149
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     <pre class="prettyprint lang-config">RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]</pre>
180
181     </div>
182
183     <div class="note"><h3>Cached lookups</h3>
184     <p>
185     The looked-up keys are cached by httpd until the <code>mtime</code>
186     (modified time) of the mapfile changes, or the httpd server is
187     restarted. This ensures better performance on maps that are called
188     by many requests.
189     </p>
190     </div>
191
192   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
193 <div class="section">
194 <h2><a name="rnd" id="rnd">rnd: Randomized Plain Text</a></h2>
195     
196
197     <p>When a MapType of <code>rnd</code> is used, the MapSource is a
198     filesystem path to a plain-text mapping file, each line of which
199     contains a key, and one or more values separated by <code>|</code>.
200     One of these values will be chosen at random if the key is
201     matched.</p>
202
203     <p>For example, you might use the following map
204     file and directives to provide a random load balancing between
205     several back-end servers, via a reverse-proxy. Images are sent
206     to one of the servers in the 'static' pool, while everything
207     else is sent to one of the 'dynamic' pool.</p>
208
209     <div class="example"><h3>Rewrite map file</h3><p><code>
210 ##<br />
211 ##  map.txt -- rewriting map<br />
212 ##<br />
213 <br />
214 static   www1|www2|www3|www4<br />
215 dynamic  www5|www6
216     </code></p></div>
217 <p><strong>Configuration directives</strong></p>
218     <pre class="prettyprint lang-config">
219 RewriteMap servers rnd:/path/to/file/map.txt
220
221 RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
222 RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
223     </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">
256 RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
257  </pre>
258
259
260     <p>The type can be sdbm, gdbm, ndbm or db.
261     However, it is recommended that you just use the <a href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
262     provided with Apache HTTP Server, as it will use the correct DBM library,
263     matching the one that was used when httpd itself was built.</p>
264
265     <p>To create a dbm file, first create a text map file as described
266     in the <a href="#txt">txt</a> section. Then run
267     <code>httxt2dbm</code>:</p>
268
269 <div class="example"><p><code>
270 $ httxt2dbm -i mapfile.txt -o mapfile.map
271 </code></p></div>
272
273 <p>You can then reference the resulting file in your
274 <code>RewriteMap</code> directive:</p>
275
276 <pre class="prettyprint lang-config">
277 RewriteMap mapname dbm:/etc/apache/mapfile.map
278 </pre>
279
280
281 <div class="note">
282 <p>Note that with some dbm types, more than one file is generated, with
283 a common base name. For example, you may have two files named
284 <code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
285 normal, and you need only use the base name <code>mapfile.map</code> in
286 your <code>RewriteMap</code> directive.</p>
287 </div>
288
289 <div class="note"><h3>Cached lookups</h3>
290 <p>
291 The looked-up keys are cached by httpd until the <code>mtime</code>
292 (modified time) of the mapfile changes, or the httpd server is
293 restarted. This ensures better performance on maps that are called
294 by many requests.
295 </p>
296 </div>
297
298   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
299 <div class="section">
300 <h2><a name="int" id="int">int: Internal Function</a></h2>
301     
302
303     <p>When a MapType of <code>int</code> is used, the MapSource is one
304     of the available internal RewriteMap functions.  Module authors can provide
305     additional internal functions by registering them with the
306     <code>ap_register_rewrite_mapfunc</code> API.
307     The functions that are provided by default are:
308     </p>
309
310     <ul>
311       <li><strong>toupper</strong>:<br />
312              Converts the key to all upper case.</li>
313       <li><strong>tolower</strong>:<br />
314              Converts the key to all lower case.</li>
315       <li><strong>escape</strong>:<br />
316              Translates special characters in the key to
317             hex-encodings.</li>
318       <li><strong>unescape</strong>:<br />
319              Translates hex-encodings in the key back to
320             special characters.</li>
321     </ul>
322
323     <p>
324     To use one of these functions, create a <code>RewriteMap</code> referencing
325     the int function, and then use that in your <code>RewriteRule</code>:
326     </p>
327
328    <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
329     <pre class="prettyprint lang-config">
330
331 RewriteMap lc int:tolower
332 RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
333     </pre>
334
335
336     <div class="note">
337     <p>Please note that the example offered here is for
338     illustration purposes only, and is not a recommendation. If you want
339     to make URLs case-insensitive, consider using
340     <code class="module"><a href="../mod/mod_speling.html">mod_speling</a></code> instead.
341     </p>
342     </div>
343
344   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
345 <div class="section">
346 <h2><a name="prg" id="prg">prg: External Rewriting Program</a></h2>
347
348     <p>When a MapType of <code>prg</code> is used, the MapSource is a
349     filesystem path to an executable program which will providing the
350     mapping behavior. This can be a compiled binary file, or a program
351     in an interpreted language such as Perl or Python.</p>
352
353     <p>This program is started once, when the Apache HTTP Server is
354     started, and then communicates with the rewriting engine via
355     <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
356     function lookup, it expects one argument via <code>STDIN</code>, and
357     should return one new-line terminated response string on
358     <code>STDOUT</code>. If there is no corresponding lookup value, the
359     map program should return the four-character string
360     "<code>NULL</code>" to indicate this.</p>
361
362     <p>External rewriting programs are not started if they're defined in
363     a context that does not have <code class="directive"><a href="../mod/mod_rewrite.html#rewriteengine">RewriteEngine</a></code> set to
364     <code>on</code>.</p>
365
366     <p>This feature utilizes the <code>rewrite-map</code> mutex,
367     which is required for reliable communication with the program.
368     The mutex mechanism and lock file can be configured with the
369     <code class="directive"><a href="../mod/core.html#mutex">Mutex</a></code> directive.</p>
370
371     <p>A simple example is shown here which will replace all dashes with
372     underscores in a request URI.</p>
373     
374 <p><strong>Rewrite configuration</strong></p>
375     <pre class="prettyprint lang-config">
376
377 RewriteMap d2u prg:/www/bin/dash2under.pl<br />
378 RewriteRule - ${d2u:%{REQUEST_URI}}
379     </pre>
380
381
382     <p><strong>dash2under.pl</strong></p>
383     <pre class="prettyprint lang-perl">
384     #!/usr/bin/perl
385     $| = 1; # Turn off I/O buffering
386     while (&lt;STDIN&gt;) {
387         s/-/_/g; # Replace dashes with underscores
388         print $_;
389     }
390     </pre>
391
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="dbd" id="dbd">dbd or fastdbd: SQL Query</a></h2>
413     
414
415     <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
416     used, the MapSource is a SQL SELECT statement that takes a single
417     argument and returns a single value.</p>
418
419     <p><code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code> will need to be configured to point at
420     the right database for this statement to be executed.</p>
421
422     <p>There are two forms of this MapType.
423     Using a MapType of <code>dbd</code> causes the query to be
424     executed with each map request, while using <code>fastdbd</code>
425     caches the database lookups internally. So, while
426     <code>fastdbd</code> is more efficient, and therefore faster, it
427     won't pick up on changes to the database until the server is
428     restarted.</p>
429
430     <p>If a query returns more than one row, a random row from
431 the result set is used.</p>
432
433         <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">
434 RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
435     </pre>
436 </div>
437
438   </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
439 <div class="section">
440 <h2><a name="summary" id="summary">Summary</a></h2>
441     
442
443     <p>The <code class="directive">RewriteMap</code> directive can occur more than
444     once. For each mapping-function use one
445     <code class="directive">RewriteMap</code> directive to declare its rewriting
446     mapfile.</p>
447
448     <p>While you cannot <strong>declare</strong> a map in
449     per-directory context (<code>.htaccess</code> files or
450     &lt;Directory&gt; blocks) it is possible to
451     <strong>use</strong> this map in per-directory context. </p>
452
453   </div></div>
454 <div class="bottomlang">
455 <p><span>Available Languages: </span><a href="../en/rewrite/rewritemap.html" title="English">&nbsp;en&nbsp;</a></p>
456 </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>
457 <script type="text/javascript"><!--//--><![CDATA[//><!--
458 var comments_shortname = 'httpd';
459 var comments_identifier = 'http://httpd.apache.org/docs/trunk/rewrite/rewritemap.html';
460 (function(w, d) {
461     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
462         d.write('<div id="comments_thread"><\/div>');
463         var s = d.createElement('script');
464         s.type = 'text/javascript';
465         s.async = true;
466         s.src = 'https://c.apaste.info/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
467         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
468     }
469     else {
470         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
471     }
472 })(window, document);
473 //--><!]]></script></div><div id="footer">
474 <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>
475 <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[//><!--
476 if (typeof(prettyPrint) !== 'undefined') {
477     prettyPrint();
478 }
479 //--><!]]></script>
480 </body></html>