From c6625b8cb87fe3da11750951a7d973f565b2e8ce Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Tue, 18 May 2010 22:25:03 +0000 Subject: [PATCH] xmllint git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@945931 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/rewrite/rewritemap.xml | 314 +++++++++++++---------------- 1 file changed, 139 insertions(+), 175 deletions(-) diff --git a/docs/manual/rewrite/rewritemap.xml b/docs/manual/rewrite/rewritemap.xml index 04af3c120b..fffda13470 100644 --- a/docs/manual/rewrite/rewritemap.xml +++ b/docs/manual/rewrite/rewritemap.xml @@ -1,8 +1,7 @@ - + - - Rewrite - -Using RewriteMap - - - -

This document supplements the mod_rewrite + Using RewriteMap +

+

This document supplements the mod_rewrite reference documentation. It describes the use of the RewriteMap directive, and provides examples of each of the various RewriteMap types.

- -Note that many of these examples won't work unchanged in your + Note that many of these examples won't work unchanged in your particular server configuration, so it's important that you understand them, rather than merely cutting and pasting the examples into your configuration. - - -Module documentation -mod_rewrite introduction -Redirection and remapping -Controlling access -Virtual hosts -Proxying -Advanced techniques and tricks -When not to use mod_rewrite - -
Introduction - -

The RewriteMap directive defines a +

+ + Module documentation + + + mod_rewrite introduction + + + Redirection and remapping + + + Controlling access + + + Virtual hosts + + + Proxying + + + Advanced techniques and tricks + + + When not to use mod_rewrite + +
+ Introduction +

The RewriteMap directive defines a Rewriting Map which can be used inside rule substitution strings by the mapping-functions to insert/substitute fields through a key lookup. The source of this lookup can be of various types.

- -

The MapName is +

The MapName is the name of the map and will be used to specify a mapping-function for the substitution strings of a rewriting rule via one of the following constructs:

- -

- ${ MapName : - LookupKey }
- ${ MapName : - LookupKey | DefaultValue - } -

- -

When such a construct occurs, the map MapName is +

+ + ${ + MapName + : + LookupKey + } +
+ ${ + MapName + : + LookupKey + | + DefaultValue + } + +

+

When such a construct occurs, the map MapName is consulted and the key LookupKey is looked-up. If the key is found, the map-function construct is substituted by SubstValue. If the key is not found then it is substituted by DefaultValue or by the empty string if no DefaultValue was specified.

- -

For example, you might define a +

For example, you might define a RewriteMap as:

- - + RewriteMap examplemap txt:/path/to/file/map.txt - -

You would then be able to use this map in a +

You would then be able to use this map in a RewriteRule as follows:

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

The following combinations for MapType and +

The following combinations for MapType and MapSource can be used:

- -
txt: Plain text maps - -

MapType: txt, MapSource: Unix filesystem +

+ txt: Plain text maps +

MapType: txt, MapSource: Unix filesystem path to valid regular file

- -

This is the standard rewriting map feature where the +

This is the standard rewriting map feature where the MapSource is a plain ASCII file containing either blank lines, comment lines (starting with a '#' character) or pairs like the following - one per line.

- -

- MatchingKey - SubstValue -

- -Example -
+    

+      
+        MatchingKey
+        SubstValue
+      
+    

+    
+      Example
+      
 ##
 ##  map.txt -- rewriting map
 ##
@@ -118,20 +127,16 @@ configuration.
 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
 Mr.Joe.Average        joe   # Mr. Average
 

-
-
-
+    
+    
 RewriteMap real-to-user txt:/path/to/file/map.txt
 
-
-
- -
Randomized Plain Text - -

MapType: rnd, MapSource: Unix filesystem +

+
+ rnd: Randomized Plain Text +

MapType: rnd, MapSource: Unix filesystem path to valid regular file

- -

This is identical to the Standard Plain Text variant +

This is identical to the Standard Plain Text variant above but with a special post-processing feature: After looking up a value it is parsed according to contained ``|'' characters which have the meaning of @@ -142,10 +147,10 @@ RewriteMap real-to-user txt:/path/to/file/map.txt 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.

-

Example:

- -Rewrite map file -
+    
Example:

+    
+      Rewrite map file
+      
 ##
 ##  map.txt -- rewriting map
 ##
@@ -153,80 +158,62 @@ RewriteMap real-to-user txt:/path/to/file/map.txt
 static   www1|www2|www3|www4
 dynamic  www5|www6
 

-
-
-Configuration directives
-RewriteMap servers rnd:/path/to/file/map.txt

-

+    
+    Configuration directives
+RewriteMap servers rnd:/path/to/file/map.txt

+

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

+[NC,P,L]

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

MapType: +

+
+ dbm: DBM Hash File +

MapType: dbm[=type], MapSource: Unix filesystem path to valid regular file

- -

Here the source is a binary format DBM file containing +

Here the source is a binary format DBM file containing the same contents as a Plain Text format file, but in a special representation which is optimized for really fast lookups. The type can be sdbm, gdbm, ndbm, or db depending on compile-time settings. If the type is omitted, the compile-time default will be chosen.

- -

To create a dbm file from a source text file, use the httxt2dbm utility.

- - +

To create a dbm file from a source text file, use the httxt2dbm utility.

+ $ httxt2dbm -i mapfile.txt -o mapfile.map -
- -
Internal Function -

+

+
+ int: Internal Function +

MapType: int, MapSource: Internal Apache httpd function

- -

Here, the source is an internal Apache httpd function. +

Here, the source is an internal Apache httpd function. Currently you cannot create your own, but the following functions already exist:

- -
    -
  • toupper:
    +
      +
    • toupper:
      Converts the key to all upper case.
      • - -
    • tolower:
      +
    • tolower:
      Converts the key to all lower case.
      • - -
    • escape:
      +
    • escape:
      Translates special characters in the key to hex-encodings.
      • - -
    • unescape:
      +
    • unescape:
      Translates hex-encodings in the key back to special characters.
      • -
    -
- -
External Rewriting Program -

+ +

+
prg: External Rewriting Program

MapType: prg, MapSource: Unix filesystem path to valid regular file -

- -

Here the source is a program, not a map file. To +

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 '#!/path/to/interpreter' as the first - line).

- -

This program is started once, when the Apache httpd server + line).

This program is started once, when the Apache httpd server is started, and then communicates with the rewriting engine via its stdin and stdout file-handles. For each map-function lookup it will @@ -235,82 +222,59 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map looked-up value as a newline-terminated string on stdout or the four-character string ``NULL'' if it fails (i.e., there - is no corresponding value for the given key).

- -

This feature utilizes the rewrite-map mutex, + is no corresponding value for the given key).

This feature utilizes the rewrite-map mutex, which is required for reliable communication with the program. The mutex mechanism and lock file can be configured with the - Mutex directive.

- -

External rewriting programs are not started if they're defined in a + Mutex directive.

External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on

.

A trivial program which will implement a 1:1 map (i.e., - key == value) could be:

- - -
+          key == value) could be:
 #!/usr/bin/perl
 $| = 1;
 while (<STDIN>) {
     # ...put here any transformations or lookups...
     print $_;
 }
-

-
-
-          
But be very careful:

-
-          
    
-            
  1. ``Keep it simple, stupid'' (KISS).
-            If this program hangs, it will cause Apache httpd to hang
-            when trying to use the relevant rewrite rule.
    2. 
-
-            
  2. A common mistake is to use buffered I/O on
-            stdout. Avoid this, as it will cause a deadloop!
-            ``$|=1'' is used above, to prevent this.
    3. 
-          

-
- -
SQL Query -

MapType: dbd or fastdbd, - MapSource: An SQL SELECT statement that takes a single - argument and returns a single value.

- -

This uses mod_dbd to implement a rewritemap - by lookup in an SQL database. There are two forms: - fastdbd caches database lookups internally, - dbd doesn't. So dbd incurs a - performance penalty but responds immediately if the database - contents are updated, while fastdbd is more - efficient but won't re-read database contents until server - restart.

-

If a query returns more than one row, a random row from - the result set is used.

- -Example +

But be very careful:

  1. ``Keep it simple, stupid'' (KISS). +If this program hangs, it will cause Apache httpd to hang +when trying to use the relevant rewrite rule.
  2. A common mistake is to use buffered I/O on +stdout. Avoid this, as it will cause a deadloop! +``$|=1'' is used above, to prevent this.
+
+ dbd or fastdbd: SQL Query +

MapType: dbd or fastdbd, +MapSource: An SQL SELECT statement that takes a single + argument and returns a single value.

+

This uses mod_dbd to implement a rewritemap +by lookup in an SQL database. There are two forms: +fastdbd caches database lookups internally, +dbd doesn't. So dbd incurs a +performance penalty but responds immediately if the database +contents are updated, while fastdbd is more +efficient but won't re-read database contents until server +restart.

+

If a query returns more than one row, a random row from +the result set is used.

+ Example RewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s" -
- -
Summary - -

The RewriteMap directive can occur more than +

+
+ Summary +

The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its rewriting mapfile. While you cannot declare a map in per-directory context it is of course possible to use this map in per-directory context.

- -Note For plain text and DBM format files the + Note For plain text and DBM format files the looked-up keys are cached in-core until the mtime of the mapfile changes or the server does a restart. This way you can have map-functions in rules which are used for every request. This is no problem, because the external lookup only happens once! - -
- - +
+ -- 2.50.1