From 63ae18dffb27624f82025e6b87bfa1511c9940b7 Mon Sep 17 00:00:00 2001 From: "Ralf S. Engelschall" Date: Mon, 23 Feb 1998 08:27:36 +0000 Subject: [PATCH] Add the new RewriteMap types `rnd' and `int' to mod_rewrite to allow Apache to be used as a Reverse Proxy (where the backend servers are choosen via a `rnd' map) and to allow mass virtual hosting without sections (where you have to fix the case of server names when translating the Host-Header to a directory structure). Together with the comitted ProxyPassReverse directive we now have solved two things the users have asked in the past: 1. The ability to use Apache as a full-featured Reverse Proxy 2. The ability to do mass virtual hosting without sections. For both topics we should write stand-alone documents (perhaps inside htdocs/manual/misc/) because they are not trivial to do, even when we now have the functionality ;-) Submitted by: Ralf S. Engelschall Reviewed by: Dean Gaudet, Ralf S. Engelschall git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@80298 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_rewrite.html | 147 ++++++++++++++++++++++--------- 1 file changed, 104 insertions(+), 43 deletions(-) diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 4856f4c55b..03a22c5622 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -256,7 +256,7 @@ RewriteLogLevel 3 Syntax: RewriteMap Mapname {txt,dbm,prg}:Filename
+>Syntax: RewriteMap MapName MapType:MapSource
Context: server config, virtual host

-The RewriteMap directive defines an external Rewriting Map +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. +to insert/substitute fields through a key lookup. The source of this +lookup can be of various types.

-The Mapname is the name of the map and will +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 +rewriting rule via one of the following constructs:

-${ Mapname : LookupKey +${ MapName : LookupKey +}
+${ MapName : LookupKey | DefaultValue }
-When such a directive occurs the map Mapname +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 directive is substituted by SubstValue. If -the key is not found then it is substituted by DefaultValue. +found, the map-function construct is substituted by SubstValue. If +the key is not found then it is substituted by DefaultValue or +the empty string if no DefaultValue was specified.

-The Filename must be a valid Unix filepath, containing one -of the following formats: +The following combinations for MapType and MapSource +can be used: -

    -
  1. Plain Text Format +
      +
    • Standard Plain Text
      + MapType: txt, MapSource: Unix filesystem path to valid regular file

      - This is a ASCII file which contains either blank lines, comment lines - (starting with a '#' character) or + 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
      - pairs - one per line. You can create such files either manually, - using your favorite editor, or by using the programs - mapcollect and mapmerge from the support - directory of the mod_rewrite distribution.

      - To declare such a map prefix, Filename with a txt: - string as in the following example: - + Example: 

      -#
-#   map.real-to-user -- maps realnames to usernames
-#
+##
+##  map.txt -- rewriting map
+##
 
 Ralf.S.Engelschall    rse   # Bastard Operator From Hell
-Dr.Fred.Klabuster     fred  # Mr. DAU
+Mr.Joe.Average        joe   # Mr. Average
 

      -RewriteMap real-to-host txt:/path/to/file/map.real-to-user
+RewriteMap real-to-host txt:/path/to/file/map.txt

      -

    • DBM Hashfile Format -

      - This is a binary NDBM format file containing the - same contents as the Plain Text Format files. You can create - such a file with any NDBM tool or with the dbmmanage program - from the support directory of the Apache distribution. +

    • Randomized Plain Text
      + MapType: rnd, MapSource: Unix filesystem path to valid regular file

      - To declare such a map prefix Filename with a dbm: - string. + 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 ``or''. Or + in other words: they indicate a set of alternatives from which the actual + returned value is choosen randomly. Although this sounds crazy and useless, it + was actually designed for load balancing in a reverse proxy situation where + the looked up values are server names. + Example: +

      + + +
      +##
+##  map.txt -- rewriting map
+##
+
+static   www1|www2|www3|www4
+dynamic  www5|www6
+
      +

      -

    • Program Format + + +
      +RewriteMap servers rnd:/path/to/file/map.txt
+
      + +

      +

    • Hash File
      + MapType: dbm, MapSource: Unix filesystem path to valid regular file +

      + Here the source is a binary NDBM format file containing the same contents + as a Plain Text format file, but in a special representation + which is optimized for really fast lookups. You can create such a file with + any NDBM tool or with the following Perl script:

      - This is a Unix executable, not a lookup file. To create it you can use + + + 
      +#!/path/to/bin/perl
+##
+##  txt2dbm -- convert txt map to dbm format
+##
+
+($txtmap, $dbmmap) = @ARGV;
+open(TXT, "<$txtmap");
+dbmopen(%DB, $dbmmap, 0644);
+while (<TXT>) {
+    next if (m|^s*#.*| or m|^s*$|);
+    $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|);
+}
+dbmclose(%DB);
+close(TXT)
      +

      + + + 
      $ txt2dbm map.txt map.db
      +

      +

    • Internal Function
      + MapType: int, MapSource: Internal Apache function +

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

        +
      • toupper:
        + Converts the looked up key to all upper case. +
      • tolower:
        + Converts the looked up key to all lower case. +
      +

      +

    • External Rewriting Program
      + MapType: prg, MapSource: Unix filesystem path to valid regular file +

      + Here the source is a Unix program, not a map file. To create it you can use the language of your choice, but the result has to be a run-able Unix - binary (i.e. either object-code or a script with the + executable (i.e. either object-code or a script with the magic cookie trick '#!/path/to/interpreter' as the first line).

      This program gets started once at startup of the Apache servers and then @@ -367,7 +431,7 @@ while (<STDIN>) {

      - But be very careful:
      + But be very careful:

      1. ``Keep the program simple, stupid'' (KISS), because if this program hangs it will lead to a hang of the Apache server @@ -376,10 +440,7 @@ while (<STDIN>) { This will cause a deadloop! Hence the ``$|=1'' in the above example...
      -

      - To declare such a map prefix Filename with a prg: - string. -

+ The RewriteMap directive can occur more than once. For each mapping-function use one RewriteMap directive to declare its -- 2.40.0