1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
6 Licensed to the Apache Software Foundation (ASF) under one or more
7 contributor license agreements. See the NOTICE file distributed with
8 this work for additional information regarding copyright ownership.
9 The ASF licenses this file to You under the Apache License, Version 2.0
10 (the "License"); you may not use this file except in compliance with
11 the License. You may obtain a copy of the License at
13 http://www.apache.org/licenses/LICENSE-2.0
15 Unless required by applicable law or agreed to in writing, software
16 distributed under the License is distributed on an "AS IS" BASIS,
17 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
18 See the License for the specific language governing permissions and
19 limitations under the License.
21 <manualpage metafile="rewritemap.xml.meta">
22 <parentdocument href="./">Rewrite</parentdocument>
23 <title>Using RewriteMap</title>
26 <p>This document supplements the <module>mod_rewrite</module>
27 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
28 the use of the <directive module="mod_rewrite">RewriteMap</directive> directive,
29 and provides examples of each of the various <code>RewriteMap</code> types.</p>
31 <note type="warning">Note that many of these examples won't work unchanged in your
32 particular server configuration, so it's important that you understand
33 them, rather than merely cutting and pasting the examples into your
37 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
38 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
39 <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
40 <seealso><a href="access.html">Controlling access</a></seealso>
41 <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
42 <seealso><a href="proxy.html">Proxying</a></seealso>
43 <seealso><a href="advanced.html">Advanced techniques</a></seealso>
44 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
46 <section id="introduction">
47 <title>Introduction</title>
50 The <directive module="mod_rewrite">RewriteMap</directive> directive
51 defines an external function which can be called in the context of
52 <directive module="mod_rewrite">RewriteRule</directive> or
53 <directive module="mod_rewrite">RewriteCond</directive> directives to
54 perform rewriting that is too complicated, or too specialized to be
55 performed just by regular expressions. The source of this lookup can
56 be any of the types listed in the sections below, and enumerated in
57 the <directive module="mod_rewrite">RewriteMap</directive> reference
60 <p>The syntax of the <code>RewriteMap</code> directive is as
63 <highlight language="config">
64 RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
67 <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
68 arbitray name that you assign to the map, and which you will use in
69 directives later on. Arguments are passed to the map via the
74 <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>
75 <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>
76 <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>
80 <p>When such a construct occurs, the map <em>MapName</em> is
81 consulted and the key <em>LookupKey</em> is looked-up. If the
82 key is found, the map-function construct is substituted by
83 <em>SubstValue</em>. If the key is not found then it is
84 substituted by <em>DefaultValue</em> or by the empty string
85 if no <em>DefaultValue</em> was specified.</p>
87 <p>For example, you can define a
88 <directive>RewriteMap</directive> as:</p>
89 <highlight language="config">
90 RewriteMap examplemap "txt:/path/to/file/map.txt"
92 <p>You would then be able to use this map in a
93 <directive>RewriteRule</directive> as follows:</p>
94 <highlight language="config">
95 RewriteRule "^/ex/(.*)" "${examplemap:$1}"
98 <p>A default value can be specified in the event that nothing is found
101 <highlight language="config">
102 RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"
105 <note><title>Per-directory and .htaccess context</title>
107 The <code>RewriteMap</code> directive may not be used in
108 <Directory> 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.
116 <p>The sections that follow describe the various <em>MapType</em>s that
117 may be used, and give examples of each.</p>
121 <title>int: Internal Function</title>
123 <p>When a MapType of <code>int</code> is used, the MapSource is one
124 of the available internal RewriteMap functions. Module authors can provide
125 additional internal functions by registering them with the
126 <code>ap_register_rewrite_mapfunc</code> API.
127 The functions that are provided by default are:
131 <li><strong>toupper</strong>:<br/>
132 Converts the key to all upper case.</li>
133 <li><strong>tolower</strong>:<br/>
134 Converts the key to all lower case.</li>
135 <li><strong>escape</strong>:<br/>
136 Translates special characters in the key to
138 <li><strong>unescape</strong>:<br/>
139 Translates hex-encodings in the key back to
140 special characters.</li>
144 To use one of these functions, create a <code>RewriteMap</code> referencing
145 the int function, and then use that in your <code>RewriteRule</code>:
148 <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
149 <highlight language="config">
150 RewriteMap lc "int:tolower"
151 RewriteRule "(.*?[A-Z]+.*)" "${lc:$1}" [R]
155 <p>Please note that the example offered here is for
156 illustration purposes only, and is not a recommendation. If you want
157 to make URLs case-insensitive, consider using
158 <module>mod_speling</module> instead.
165 <title>txt: Plain text maps</title>
167 <p>When a MapType of <code>txt</code> is used, the MapSource is a filesystem path to a
168 plain-text mapping file, containing space-separated key/value pair
169 per line. Optionally, a line may be contain a comment, starting with
172 <p>A valid text rewrite map file will have the following syntax:</p>
176 <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
177 <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
180 <p>When the RewriteMap is invoked the argument is looked for in the
181 first argument of a line, and, if found, the substitution value is
184 <p>For example, we can use a mapfile to translate product names to
185 product IDs for easier-to-remember URLs, using the following
187 <p><strong>Product to ID configuration</strong></p>
188 <highlight language="config">
189 RewriteMap product2id "txt:/etc/apache2/productmap.txt"
190 RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
193 <p>We assume here that the <code>prods.php</code> script knows what
194 to do when it received an argument of <code>id=NOTFOUND</code> when
195 a product is not found in the lookup map.</p>
197 <p>The file <code>/etc/apache2/productmap.txt</code> then contains
200 <example><title>Product to ID map</title>
202 ## productmap.txt - Product to ID map file<br />
212 <p>Thus, when <code>http://example.com/product/television</code> is
213 requested, the <code>RewriteRule</code> is applied, and the request
214 is internally mapped to <code>/prods.php?id=993</code>.</p>
216 <note><title>Note: .htaccess files</title>
217 The example given is crafted to be used in server or virtualhost
218 scope. If you're planning to use this in a <code>.htaccess</code>
219 file, you'll need to remove the leading slash from the rewrite
220 pattern in order for it to match anything:
221 <highlight language="config">
222 RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
226 <note><title>Cached lookups</title>
228 The looked-up keys are cached by httpd until the <code>mtime</code>
229 (modified time) of the mapfile changes, or the httpd server is
230 restarted. This ensures better performance on maps that are called
237 <title>rnd: Randomized Plain Text</title>
239 <p>When a MapType of <code>rnd</code> is used, the MapSource is a
240 filesystem path to a plain-text mapping file, each line of which
241 contains a key, and one or more values separated by <code>|</code>.
242 One of these values will be chosen at random if the key is
245 <p>For example, you can use the following map
246 file and directives to provide a random load balancing between
247 several back-end servers, via a reverse-proxy. Images are sent
248 to one of the servers in the 'static' pool, while everything
249 else is sent to one of the 'dynamic' pool.</p>
251 <example><title>Rewrite map file</title>
253 ## map.txt -- rewriting map<br />
256 static www1|www2|www3|www4<br />
259 <p><strong>Configuration directives</strong></p>
260 <highlight language="config">
261 RewriteMap servers "rnd:/path/to/file/map.txt"
263 RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
264 RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]
267 <p>So, when an image is requested and the first of these rules is
268 matched, <code>RewriteMap</code> looks up the string
269 <code>static</code> in the map file, which returns one of the
270 specified hostnames at random, which is then used in the
271 <code>RewriteRule</code> target.</p>
273 <p>If you wanted to have one of the servers more likely to be chosen
274 (for example, if one of the server has more memory than the others,
275 and so can handle more requests) simply list it more times in the
279 static www1|www1|www2|www3|www4
285 <title>dbm: DBM Hash File</title>
287 <p>When a MapType of <code>dbm</code> is used, the MapSource is a
288 filesystem path to a DBM database file containing key/value pairs to
289 be used in the mapping. This works exactly the same way as the
290 <code>txt</code> map, but is much faster, because a DBM is indexed,
291 whereas a text file is not. This allows more rapid access to the
294 <p>You may optionally specify a particular dbm type:</p>
296 <highlight language="config">
297 RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"
300 <p>The type can be sdbm, gdbm, ndbm or db.
301 However, it is recommended that you just use the <a
302 href="../programs/httxt2dbm.html">httxt2dbm</a> utility that is
303 provided with Apache HTTP Server, as it will use the correct DBM library,
304 matching the one that was used when httpd itself was built.</p>
306 <p>To create a dbm file, first create a text map file as described
307 in the <a href="#txt">txt</a> section. Then run
308 <code>httxt2dbm</code>:</p>
311 $ httxt2dbm -i mapfile.txt -o mapfile.map
314 <p>You can then reference the resulting file in your
315 <code>RewriteMap</code> directive:</p>
317 <highlight language="config">
318 RewriteMap mapname "dbm:/etc/apache/mapfile.map"
322 <p>Note that with some dbm types, more than one file is generated, with
323 a common base name. For example, you may have two files named
324 <code>mapfile.map.dir</code> and <code>mapfiile.map.pag</code>. This is
325 normal, and you need only use the base name <code>mapfile.map</code> in
326 your <code>RewriteMap</code> directive.</p>
329 <note><title>Cached lookups</title>
331 The looked-up keys are cached by httpd until the <code>mtime</code>
332 (modified time) of the mapfile changes, or the httpd server is
333 restarted. This ensures better performance on maps that are called
340 <section id="prg"><title>prg: External Rewriting Program</title>
342 <p>When a MapType of <code>prg</code> is used, the MapSource is a
343 filesystem path to an executable program which will providing the
344 mapping behavior. This can be a compiled binary file, or a program
345 in an interpreted language such as Perl or Python.</p>
347 <p>This program is started once, when the Apache HTTP Server is
348 started, and then communicates with the rewriting engine via
349 <code>STDIN</code> and <code>STDOUT</code>. That is, for each map
350 function lookup, it expects one argument via <code>STDIN</code>, and
351 should return one new-line terminated response string on
352 <code>STDOUT</code>. If there is no corresponding lookup value, the
353 map program should return the four-character string
354 "<code>NULL</code>" to indicate this.</p>
356 <p>External rewriting programs are not started if they're defined in
357 a context that does not have <directive
358 module="mod_rewrite">RewriteEngine</directive> set to
361 <p>By default, external rewriting programs are run as the
362 user:group who started httpd. This can be changed on UNIX systems
363 by passing user name and group name as third argument to
364 <directive module="mod_rewrite">RewriteMap</directive> in the
365 <code>username:groupname</code> format.</p>
367 <p>This feature utilizes the <code>rewrite-map</code> mutex,
368 which is required for reliable communication with the program.
369 The mutex mechanism and lock file can be configured with the
370 <directive module="core">Mutex</directive> directive.</p>
372 <p>A simple example is shown here which will replace all dashes with
373 underscores in a request URI.</p>
375 <p><strong>Rewrite configuration</strong></p>
376 <highlight language="config">
377 RewriteMap d2u "prg:/www/bin/dash2under.programlisting" apache:apache<br />
378 RewriteRule "-" "${d2u:%{REQUEST_URI}}"
381 <p><strong>dash2under.pl</strong></p>
382 <highlight language="perl">
384 $| = 1; # Turn off I/O buffering
385 while (<STDIN>) {
386 s/-/_/g; # Replace dashes with underscores
391 <note><title>Caution!</title>
393 <li>Keep your rewrite map program as simple as possible. If the program
394 hangs, it will cause httpd to wait indefinitely for a response from the
395 map, which will, in turn, cause httpd to stop responding to
397 <li>Be sure to turn off buffering in your program. In Perl this is done
398 by the second line in the example script: <code>$| = 1;</code> This will
399 of course vary in other languages. Buffered I/O will cause httpd to wait
400 for the output, and so it will hang.</li>
401 <li>Remember that there is only one copy of the program, started at
402 server startup. All requests will need to go through this one bottleneck.
403 This can cause significant slowdowns if many requests must go through
404 this process, or if the script itself is very slow.</li>
412 <title>dbd or fastdbd: SQL Query</title>
414 <p>When a MapType of <code>dbd</code> or <code>fastdbd</code> is
415 used, the MapSource is a SQL SELECT statement that takes a single
416 argument and returns a single value.</p>
418 <p><module>mod_dbd</module> will need to be configured to point at
419 the right database for this statement to be executed.</p>
421 <p>There are two forms of this MapType.
422 Using a MapType of <code>dbd</code> causes the query to be
423 executed with each map request, while using <code>fastdbd</code>
424 caches the database lookups internally. So, while
425 <code>fastdbd</code> is more efficient, and therefore faster, it
426 won't pick up on changes to the database until the server is
429 <p>If a query returns more than one row, a random row from
430 the result set is used.</p>
432 <example><title>Example</title>
433 <highlight language="config">
434 RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
439 <section id="summary">
440 <title>Summary</title>
442 <p>The <directive>RewriteMap</directive> directive can occur more than
443 once. For each mapping-function use one
444 <directive>RewriteMap</directive> directive to declare its rewriting
447 <p>While you cannot <strong>declare</strong> a map in
448 per-directory context (<code>.htaccess</code> files or
449 <Directory> blocks) it is possible to
450 <strong>use</strong> this map in per-directory context. </p>