<p>The syntax of the <code>RewriteMap</code> directive is as
follows:</p>
-<highlight language="config">RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em></highlight>
+<highlight language="config">
+RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
+</highlight>
<p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is an
arbitray name that you assign to the map, and which you will use in
substituted by <em>DefaultValue</em> or by the empty string
if no <em>DefaultValue</em> was specified.</p>
- <p>For example, you might define a
+ <p>For example, you can define a
<directive>RewriteMap</directive> as:</p>
- <highlight language="config">RewriteMap examplemap txt:/path/to/file/map.txt</highlight>
+ <highlight language="config">
+RewriteMap examplemap "txt:/path/to/file/map.txt"
+ </highlight>
<p>You would then be able to use this map in a
<directive>RewriteRule</directive> as follows:</p>
-<highlight language="config">RewriteRule ^/ex/(.*) ${examplemap:$1}</highlight>
+ <highlight language="config">
+RewriteRule "^/ex/(.*)" "${examplemap:$1}"
+ </highlight>
<p>A default value can be specified in the event that nothing is found
in the map:</p>
-<highlight language="config">RewriteRule ^/ex/(.*) ${examplemap:$1|/not_found.html}</highlight>
+<highlight language="config">
+RewriteRule "^/ex/(.*)" "${examplemap:$1|/not_found.html}"
+</highlight>
<note><title>Per-directory and .htaccess context</title>
<p>
may be used, and give examples of each.</p>
</section>
+ <section id="int">
+ <title>int: Internal Function</title>
+
+ <p>When a MapType of <code>int</code> is used, the MapSource is one
+ of the available internal RewriteMap functions. Module authors can provide
+ additional internal functions by registering them with the
+ <code>ap_register_rewrite_mapfunc</code> API.
+ The functions that are provided by default are:
+ </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>
+
+ <p>
+ To use one of these functions, create a <code>RewriteMap</code> referencing
+ the int function, and then use that in your <code>RewriteRule</code>:
+ </p>
+
+ <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
+ <highlight language="config">
+RewriteMap lc "int:tolower"
+RewriteRule "(.*?[A-Z]+.*)" "${lc:$1}" [R]
+ </highlight>
+
+ <note>
+ <p>Please note that the example offered here is for
+ illustration purposes only, and is not a recommendation. If you want
+ to make URLs case-insensitive, consider using
+ <module>mod_speling</module> instead.
+ </p>
+ </note>
+
+ </section>
+
<section id="txt">
<title>txt: Plain text maps</title>
per line. Optionally, a line may be contain a comment, starting with
a '#' character.</p>
- <p>For example, the following might be valid entries in a map
- file.</p>
+ <p>A valid text rewrite map file will have the following syntax:</p>
- <p class="indent">
+ <example>
# Comment line<br />
<strong><em>MatchingKey</em> <em>SubstValue</em></strong><br />
<strong><em>MatchingKey</em> <em>SubstValue</em></strong> # comment<br />
- </p>
+ </example>
<p>When the RewriteMap is invoked the argument is looked for in the
first argument of a line, and, if found, the substitution value is
returned.</p>
- <p>For example, we might use a mapfile to translate product names to
+ <p>For example, we can use a mapfile to translate product names to
product IDs for easier-to-remember URLs, using the following
recipe:</p>
<p><strong>Product to ID configuration</strong></p>
<highlight language="config">
-RewriteMap product2id txt:/etc/apache2/productmap.txt
-RewriteRule ^/product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]
+RewriteMap product2id "txt:/etc/apache2/productmap.txt"
+RewriteRule "^/product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
</highlight>
<p>We assume here that the <code>prods.php</code> script knows what
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:
- <highlight language="config">RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]</highlight>
+ <highlight language="config">
+RewriteRule "^product/(.*)" "/prods.php?id=${product2id:$1|NOTFOUND}" [PT]
+ </highlight>
</note>
<note><title>Cached lookups</title>
One of these values will be chosen at random if the key is
matched.</p>
- <p>For example, you might use the following map
+ <p>For example, you can use the following map
file and directives to provide a random load balancing between
several back-end servers, via a reverse-proxy. Images are sent
to one of the servers in the 'static' pool, while everything
</example>
<p><strong>Configuration directives</strong></p>
<highlight language="config">
-RewriteMap servers rnd:/path/to/file/map.txt
+RewriteMap servers "rnd:/path/to/file/map.txt"
-RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 [NC,P,L]
-RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
+RewriteRule "^/(.*\.(png|gif|jpg))" "http://${servers:static}/$1" [NC,P,L]
+RewriteRule "^/(.*)" "http://${servers:dynamic}/$1" [P,L]
</highlight>
<p>So, when an image is requested and the first of these rules is
<p>You may optionally specify a particular dbm type:</p>
<highlight language="config">
-RewriteMap examplemap dbm=sdbm:/etc/apache/mapfile.dbm
+RewriteMap examplemap "dbm=sdbm:/etc/apache/mapfile.dbm"
</highlight>
<p>The type can be sdbm, gdbm, ndbm or db.
<code>RewriteMap</code> directive:</p>
<highlight language="config">
-RewriteMap mapname dbm:/etc/apache/mapfile.map
+RewriteMap mapname "dbm:/etc/apache/mapfile.map"
</highlight>
<note>
</section>
- <section id="int">
- <title>int: Internal Function</title>
-
- <p>When a MapType of <code>int</code> is used, the MapSource is one
- of the available internal RewriteMap functions. Module authors can provide
- additional internal functions by registering them with the
- <code>ap_register_rewrite_mapfunc</code> API.
- The functions that are provided by default are:
- </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>
-
- <p>
- To use one of these functions, create a <code>RewriteMap</code> referencing
- the int function, and then use that in your <code>RewriteRule</code>:
- </p>
-
- <p> <strong>Redirect a URI to an all-lowercase version of itself</strong></p>
- <highlight language="config">
-
-RewriteMap lc int:tolower
-RewriteRule (.*?[A-Z]+.*) ${lc:$1} [R]
- </highlight>
-
- <note>
- <p>Please note that the example offered here is for
- illustration purposes only, and is not a recommendation. If you want
- to make URLs case-insensitive, consider using
- <module>mod_speling</module> instead.
- </p>
- </note>
-
- </section>
-
<section id="prg"><title>prg: External Rewriting Program</title>
<p>When a MapType of <code>prg</code> is used, the MapSource is a
module="mod_rewrite">RewriteEngine</directive> set to
<code>on</code>.</p>
+ <p>By default, external rewriting programs are run as the
+ user:group who started httpd. This can be changed on UNIX systems
+ by passing user name and group name as third argument to
+ <directive module="mod_rewrite">RewriteMap</directive> in the
+ <code>username:groupname</code> format.</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
<p>A simple example is shown here which will replace all dashes with
underscores in a request URI.</p>
-
+
<p><strong>Rewrite configuration</strong></p>
<highlight language="config">
-
-RewriteMap d2u prg:/www/bin/dash2under.pl<br />
-RewriteRule - ${d2u:%{REQUEST_URI}}
+RewriteMap d2u "prg:/www/bin/dash2under.programlisting" apache:apache<br />
+RewriteRule "-" "${d2u:%{REQUEST_URI}}"
</highlight>
<p><strong>dash2under.pl</strong></p>
projects / apache / blobdiff