GCS Amplitude
GCS Amplitude

Using RewriteMap

Comment line

comment

```

productmap.txt - Product to ID map file

television 993

map.txt -- rewriting map

static www1|www2|www3|www4

Turn off I/O buffering while () { s/-/_/g;

Replace dashes with underscores print $_; }

directive defines an external function which can be called in the context of RewriteMap

directives to perform rewriting that is too complicated, or too specialized to be performed just by regular expressions. The source of this lookup can be any of the types listed in the sections below, and enumerated in the RewriteCond

directive is as follows:

The [ MapName] is an arbitray name that you assign to the map, and which you will use in directives later on. Arguments are passed to the map via the following syntax:

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 RewriteMap

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

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

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

A default value can be specified in the event that nothing is found in the map:

directive may not be used in sections or .htaccess

files. You must declare the map in server or virtualhost context. You may use the map, once created, in your RewriteRule

directives in those scopes. You just can't declare it in those scopes.

The sections that follow describe the various MapTypes that may be used, and give examples of each.

is used, the MapSource is a filesystem path to a plain-text mapping file, containing space-separated key/value pair per line. Optionally, a line may be contain a comment, starting with a '#' character.

For example, the following might be valid entries in a map file.

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.

For example, we might use a mapfile to translate product names to product IDs for easier-to-remember URLs, using the following recipe:

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

We assume here that the prods.php

script knows what to do when it received an argument of id=NOTFOUND

is applied, and the request is internally mapped to /prods.php?id=993

file, you'll need to remove the leading slash from the rewrite pattern in order for it to match anything: RewriteRule ^product/(.*) /prods.php?id=${product2id:$1|NOTFOUND} [PT]

The looked-up keys are cached by httpd until the mtime

(modified time) of the mapfile changes, or the httpd server is restarted. This ensures better performance on maps that are called by many requests.

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 |

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

For example, you might 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 else is sent to one of the 'dynamic' pool.

So, when an image is requested and the first of these rules is matched, RewriteMap

in the map file, which returns one of the specified hostnames at random, which is then used in the RewriteRule

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.

is used, the MapSource is a filesystem path to a DBM database file containing key/value pairs to be used in the mapping. This works exactly the same way as the txt

map, but is much faster, because a DBM is indexed, whereas a text file is not. This allows more rapid access to the desired key.

You may optionally specify a particular dbm type:

The type can be sdbm, gdbm, ndbm or db. However, it is recommended that you just use the httxt2dbm utility that is provided with Apache HTTP Server, as it will use the correct DBM library, matching the one that was used when httpd itself was built.

To create a dbm file, first create a text map file as described in the txt section. Then run httxt2dbm

Note that with some dbm types, more than one file is generated, with a common base name. For example, you may have two files named mapfile.map.dir

and mapfiile.map.pag

. This is normal, and you need only use the base name mapfile.map

is used, the MapSource is one of the available internal RewriteMap functions. Module authors can provide additional internal functions by registering them with the apregisterrewrite_mapfunc

Redirect a URI to an all-lowercase version of itself

RewriteMap lc int:tolower RewriteRule (.?[A-Z]+.) ${lc:$1} [R]

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

is used, the MapSource is a filesystem path to an executable program which will providing the mapping behavior. This can be a compiled binary file, or a program in an interpreted language such as Perl or Python.

This program is started once, when the Apache HTTP Server is started, and then communicates with the rewriting engine via STDIN

, and should return one new-line terminated response string on STDOUT

. If there is no corresponding lookup value, the map program should return the four-character string "NULL

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

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

A simple example is shown here which will replace all dashes with underscores in a request URI.

RewriteMap d2u prg:/www/bin/dash2under.pl

This will of course vary in other languages. Buffered I/O will cause httpd to wait for the output, and so it will hang.When a MapType of dbd

is used, the MapSource is a SQL SELECT statement that takes a single argument and returns a single value.

will need to be configured to point at the right database for this statement to be executed.mod_dbd

caches the database lookups internally. So, while fastdbd

is more efficient, and therefore faster, it won't pick up on changes to the database until the server is restarted.

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

files or blocks) it is possible to use this map in per-directory context.

Modules | Directives | FAQ | Glossary | Sitemap

Apache HTTP Server Version 2.4

Using RewriteMap

Available Languages: en | fr

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.

mod_rewrite
RewriteMap
RewriteMap

See also

Introduction

txt: Plain text maps

rnd: Randomized Plain Text

dbm: DBM Hash File

int: Internal Function

prg: External Rewriting Program

dbd or fastdbd: SQL Query

Summary