97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml version="1.0" encoding="UTF-8"?>

97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd<manualpage metafile="rewritemap.xml.meta">

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <parentdocument href="./">Rewrite</parentdocument>

3f08db06526d6901aa08c110b5bc7dde6bc39905nd <title>Using RewriteMap</title>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <summary>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <p>This document supplements the <module>mod_rewrite</module>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes

660c7c6d7e175238807ffc144c0f8e746bf2cfb0minfrinthe use of the <directive module="mod_rewrite">RewriteMap</directive> directive,

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0ndand provides examples of each of the various <code>RewriteMap</code> types.</p>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <note type="warning">Note that many of these examples won't work unchanged in your

fe64b2ba25510d8c9dba5560a2d537763566cf40ndparticular server configuration, so it's important that you understand

fe64b2ba25510d8c9dba5560a2d537763566cf40ndthem, rather than merely cutting and pasting the examples into your

fe64b2ba25510d8c9dba5560a2d537763566cf40ndconfiguration.</note>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

fe64b2ba25510d8c9dba5560a2d537763566cf40nd </summary>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <seealso><a href="remapping.html">Redirection and remapping</a></seealso>

97a9a944b5887e91042b019776c41d5dd74557aferikabele <seealso><a href="access.html">Controlling access</a></seealso>

f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd <seealso><a href="vhosts.html">Virtual hosts</a></seealso>

f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd <seealso><a href="proxy.html">Proxying</a></seealso>

f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <section id="introduction">

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <title>Introduction</title>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd <p>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive The <directive module="mod_rewrite">RewriteMap</directive> directive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive defines an external function which can be called in the context of

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <directive module="mod_rewrite">RewriteRule</directive> or

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <directive module="mod_rewrite">RewriteCond</directive> directives to

136489fb8f0fe36dbcad3064a335eb86bfbeb5c6rbowen perform rewriting that is too complicated, or too specialized to be

97a9a944b5887e91042b019776c41d5dd74557aferikabele performed just by regular expressions. The source of this lookup can

06ba4a61654b3763ad65f52283832ebf058fdf1cslive be any of the types listed in the sections below, and enumerated in

06ba4a61654b3763ad65f52283832ebf058fdf1cslive the <directive module="mod_rewrite">RewriteMap</directive> reference

97a9a944b5887e91042b019776c41d5dd74557aferikabele documentation.</p>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The syntax of the <code>RewriteMap</code> directive is as

06ba4a61654b3763ad65f52283832ebf058fdf1cslive follows:</p>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

fe64b2ba25510d8c9dba5560a2d537763566cf40nd<example>

fe64b2ba25510d8c9dba5560a2d537763566cf40ndRewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton</example>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

117c1f888a14e73cdd821dc6c23eb0411144a41cnd <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an

117c1f888a14e73cdd821dc6c23eb0411144a41cnd arbitray name that you assign to the map, and which you will use in

117c1f888a14e73cdd821dc6c23eb0411144a41cnd directives later on. Arguments are passed to the map via the

fe64b2ba25510d8c9dba5560a2d537763566cf40nd following syntax:</p>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p class="indent">

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <strong>

9bcfc3697a91b5215893a7d0206865b13fc72148nd <code>${</code> <em>MapName</em> <code>:</code> <em>LookupKey</em>

9bcfc3697a91b5215893a7d0206865b13fc72148nd <code>}</code> <br/> <code>${</code> <em>MapName</em> <code>:</code>

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedooh <em>LookupKey</em> <code>|</code> <em>DefaultValue</em> <code>}</code>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd </strong>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton </p>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>When such a construct occurs, the map <em>MapName</em> is

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton consulted and the key <em>LookupKey</em> is looked-up. If the

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton key is found, the map-function construct is substituted by

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <em>SubstValue</em>. If the key is not found then it is

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton substituted by <em>DefaultValue</em> or by the empty string

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton if no <em>DefaultValue</em> was specified.</p>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>For example, you might define a

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <directive>RewriteMap</directive> as:</p>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <example>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton RewriteMap examplemap txt:/path/to/file/map.txt

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton </example>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <p>You would then be able to use this map in a

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton <directive>RewriteRule</directive> as follows:</p>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<example>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton RewriteRule ^/ex/(.*) ${examplemap:$1}

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton</example>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<p>A default value can be specified in the event that nothing is found

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonin the map:</p>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjorton<example>

a1ceb0cd0152edea3c72f4d9dcb352bae6ef273fjortonRewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}

fe64b2ba25510d8c9dba5560a2d537763566cf40nd</example>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p>The sections that follow describe the various <em>MapType</em>s that

75241911a05371c31eb43e91cd40645a905408cccolmmay be used, and give examples of each.</p>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd </section>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh <section id="txt">

3ffe84681ed8add175b7b33f1985d9db941eccaftrawick <title>txt: Plain text maps</title>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

fe64b2ba25510d8c9dba5560a2d537763566cf40nd <p>When a MapType of <code>txt</code>is used, the MapSource is a filesystem path to a

fe64b2ba25510d8c9dba5560a2d537763566cf40nd plain-text mapping file, containing space-separated key/value pair

75241911a05371c31eb43e91cd40645a905408cccolm per line. Optionally, a line may be contain a comment, starting with

d8e53ebbaf8cdc872236a202b5a9fc9997348a34covener a '#' character.</p>

75241911a05371c31eb43e91cd40645a905408cccolm

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>For example, the following might be valid entries in a map

06ba4a61654b3763ad65f52283832ebf058fdf1cslive file.</p>

06ba4a61654b3763ad65f52283832ebf058fdf1cslive

06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p class="indent">

f2c4476994729750806eaa70d8b55fa2b3eba25brbowen # Comment line<br />

bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh <strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />

bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh <strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />

bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh </p>

bbe82c56451e415b93ac24e6ad928dcac01519e1humbedooh

e487d6c09669296f94a5190cc34586a98e624a00nd <p>When the RewriteMap is invoked the argument is looked for in the

f67d046f3809f2659fa2b9842ca17ff87a1f01c4nd first argument of a line, and, if found, the substitution value is

23255b04d466bf2621c4dd4ae1b025a9c5639e1ahumbedooh returned.</p>

e487d6c09669296f94a5190cc34586a98e624a00nd

f2c4476994729750806eaa70d8b55fa2b3eba25brbowen <p>For example, we might use a mapfile to translate product names to

fe64b2ba25510d8c9dba5560a2d537763566cf40nd product IDs for easier-to-remember URLs, using the following

fe64b2ba25510d8c9dba5560a2d537763566cf40nd recipe:</p>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

3b3b7fc78d1f5bfc2769903375050048ff41ff26nd <example><title>Product to ID configuration</title>

ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd RewriteMap product2id txt:/etc/apache2/productmap.txt<br />

660c7c6d7e175238807ffc144c0f8e746bf2cfb0minfrin RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]

7f5b59ccc63c0c0e3e678a168f09ee6a2f51f9d0nd </example>

f086b4b402fa9a2fefc7dda85de2a3cc1cd0a654rjung

727872d18412fc021f03969b8641810d8896820bhumbedooh <p>We assume here that the <code>prods.php</code> script knows what

0d0ba3a410038e179b695446bb149cce6264e0abnd to do when it received an argument of <code>id=NOTFOUND</code> when

727872d18412fc021f03969b8641810d8896820bhumbedooh a product is not found in the lookup map.</p>

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh

0d0ba3a410038e179b695446bb149cce6264e0abnd <p>The file <code>/etc/apache2/productmap.txt</code> then contains

cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedooh the following:</p>

727872d18412fc021f03969b8641810d8896820bhumbedooh

0d0ba3a410038e179b695446bb149cce6264e0abnd <example><title>Product to ID map</title>

0d0ba3a410038e179b695446bb149cce6264e0abnd <pre>

0d0ba3a410038e179b695446bb149cce6264e0abnd##

ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedooh## productmap.txt - Product to ID map file

0d0ba3a410038e179b695446bb149cce6264e0abnd##

0d0ba3a410038e179b695446bb149cce6264e0abnd

0d0ba3a410038e179b695446bb149cce6264e0abndtelevision 993

727872d18412fc021f03969b8641810d8896820bhumbedoohstereo 198

0d0ba3a410038e179b695446bb149cce6264e0abndfishingrod 043

0d0ba3a410038e179b695446bb149cce6264e0abndbasketball 418

30471a4650391f57975f60bbb6e4a90be7b284bfhumbedoohtelephone 328

07dc96d063d49299da433f84b5c5681da9bbdf68rbowen</pre>

af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen </example>

0d0ba3a410038e179b695446bb149cce6264e0abnd

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd <p>Thus, when <code>http://example.com/product/television</code> is

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd requested, the <code>RewriteRule</code> is applied, and the request

7fec19672a491661b2fe4b29f685bc7f4efa64d4nd is internally mapped to <code>/prods.php?id=993</code>.</p>

fe64b2ba25510d8c9dba5560a2d537763566cf40nd

<note><title>Note: .htaccess files</title>

The example given is crafted to be used in server or virtualhost

scope. If you're planning to use this in a <code>.htaccess</code>

file, you'll need to remove the leading slash from the rewrite

pattern in order for it to match anything:

<example>

RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]

</example>

</note>

</section>

<section id="rnd">

<title>rnd: Randomized Plain Text</title>

<p>When a MapType of <code>rnd</code> is used, the MapSource is a

filesystem path to a plain-text mapping file, each line of which

contains a key, and one or more values separated by <code>|</code>.

One of these values will be chosen at random if the key is

matched.</p>

<p>For example, you might use the following map

file and directives to provide a random load balancing between

several back-end server, via a reverse-proxy. Images are sent

to one of the servers in the 'static' pool, while everything

else is sent to one of the 'dynamic' pool.</p>

<example><title>Rewrite map file</title>

<pre>

##

## map.txt -- rewriting map

##

static www1|www2|www3|www4

dynamic www5|www6

</pre>

</example>

<example><title>Configuration directives</title>

RewriteMap servers rnd:/path/to/file/map.txt<br/>

<br/>

RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]<br/>

RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]

</example>

<p>So, when an image is requested and the first of these rules is

matched, <code>RewriteMap</code> looks up the string

<code>static</code> in the map file, which returns one of the

specified hostnames at random, which is then used in the

<code>RewriteRule</code> target.</p>

<p>If you wanted to have one of the servers more likely to be chosen

(for example, if one of the server has more memory than the others,

and so can handle more requests) simply list it more times in the

map file.</p>

<example>

static www1|www1|www2|www3|www4

</example>

</section>

<section id="dbm">

<title>dbm: DBM Hash File</title>

<p>MapType:

<code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem

path to valid regular file</p>

<p>Here the source is a binary format DBM file containing

the same contents as a <em>Plain Text</em> format file, but

in a special representation which is optimized for really

fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or

db depending on <a href="/install.html#dbm">compile-time

settings</a>. If the <em>type</em> is omitted, the

compile-time default will be chosen.</p>

<p>To create a dbm file from a source text file, use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>

<example>

$ httxt2dbm -i mapfile.txt -o mapfile.map

</example>

</section>

<section id="int">

<title>int: Internal Function</title>

<p>

MapType: <code>int</code>, MapSource: Internal Apache httpd

function</p>

<p>Here, the source is an internal Apache httpd function.

Currently you cannot create your own, but the following

functions already exist:</p>

<ul>

<li><strong>toupper</strong>:<br/>

Converts the key to all upper case.</li>

<li><strong>tolower</strong>:<br/>

Converts the key to all lower case.</li>

<li><strong>escape</strong>:<br/>

Translates special characters in the key to

hex-encodings.</li>

<li><strong>unescape</strong>:<br/>

Translates hex-encodings in the key back to

special characters.</li>

</ul>

</section>

<section id="prg"><title>prg: External Rewriting Program</title>

<p>MapType: <code>prg</code>, MapSource: Unix filesystem path to valid regular file </p>

<p>Here the source is a program, not a map file. To

create it you can use a language of your choice, but

the result has to be an executable program (either

object-code or a script with the magic cookie trick

'<code>#!/path/to/interpreter</code>' as the first

line).</p><p>This program is started once, when the Apache httpd server

is started, and then communicates with the rewriting engine

via its <code>stdin</code> and <code>stdout</code>

file-handles. For each map-function lookup it will

receive the key to lookup as a newline-terminated string

on <code>stdin</code>. It then has to give back the

looked-up value as a newline-terminated string on

<code>stdout</code> or the four-character string

``<code>NULL</code>'' if it fails (<em>i.e.</em>, there

is no corresponding value for the given key).</p><p>This feature utilizes the <code>rewrite-map</code> mutex,

which is required for reliable communication with the program.

The mutex mechanism and lock file can be configured with the

<directive module="core">Mutex</directive> directive.</p><p>External rewriting programs are not started if they're defined in a

context that does not have <directive>RewriteEngine</directive> set to

<code>on</code></p>.

<p>A trivial program which will implement a 1:1 map (<em>i.e.</em>,

key == value) could be:</p><example><pre>

#!/usr/bin/perl

$| = 1;

while (&lt;STDIN&gt;) {

# ...put here any transformations or lookups...

print $_;

}

</pre></example><p>But be very careful:</p><ol><li>``<em>Keep it simple, stupid</em>'' (KISS).

If this program hangs, it will cause Apache httpd to hang

when trying to use the relevant rewrite rule.</li><li>A common mistake is to use buffered I/O on

<code>stdout</code>. Avoid this, as it will cause a deadloop!

``<code>$|=1</code>'' is used above, to prevent this.</li></ol></section>

<section id="dbd">

<title>dbd or fastdbd: SQL Query</title>

<p>MapType: <code>dbd</code> or <code>fastdbd</code>,

MapSource: An SQL SELECT statement that takes a single

argument and returns a single value.</p>

<p>This uses <module>mod_dbd</module> to implement a rewritemap

by lookup in an SQL database. There are two forms:

<code>fastdbd</code> caches database lookups internally,

<code>dbd</code> doesn't. So <code>dbd</code> incurs a

performance penalty but responds immediately if the database

contents are updated, while <code>fastdbd</code> is more

efficient but won't re-read database contents until server

restart.</p>

<p>If a query returns more than one row, a random row from

the result set is used.</p>

<example><title>Example</title>

RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"

</example>

</section>

<section id="summary">

<title>Summary</title>

<p>The <directive>RewriteMap</directive> directive can occur more than

once. For each mapping-function use one

<directive>RewriteMap</directive> directive to declare its rewriting

mapfile. While you cannot <strong>declare</strong> a map in

per-directory context it is of course possible to

<strong>use</strong> this map in per-directory context. </p>

<note><title>Note</title> For plain text and DBM format files the

looked-up keys are cached in-core until the <code>mtime</code> of the

mapfile changes or the server does a restart. This way you can have

map-functions in rules which are used for <strong>every</strong>

request. This is no problem, because the external lookup only happens

once!

</note>

</section>

</manualpage>