IIS Mod-Rewrite documentation
Overview Documentation    Quick overview    Rewrite directives       RewriteEngine       RewriteRule       RewriteCond       RewriteMap       RewriteOptions       RewriteLog       RewriteLogLevel       RewriteBase       RewriteLock    Support directives    Extended directives    Control center    Apache compatibility Download Purchase FAQ  
IIS Mod-Rewrite - URL rewrite tool for IIS

RewriteMap Directive

RewriteMap directive is used for name/value mapping. There are five types of mapping functions supported:

  • int: internal mapping functions.
  • txt: text based mapping table.
  • rnd: random values through a text based mapping table.
  • dbm: hash based mapping table.
  • prg: script based mapping program.

RewriteMap directive can be used more than once in a rewrite configuration. If you define multiple maps in a rewrite configuration, make sure you specify a different name for every map.

Configuration context
  • per-server configurations
  • per-virtual-host configurations

RewriteMap map_name type:source

It requires two arguments. map_name is the name of the defined map. This name is used as a reference to the specific map when a mapped value is expanded by using the ${mapname:key|default} expander in RewriteRule or RewriteCond. The behavior of the map is defined by type. This argument must always be followed by the source, whose meaning depends on the map type.

Map types

Type Description

This type of map uses one of the four supported internal functions. The name of every function is used as the source:

  • toupper: Converts all characters in key to upper case.
  • tolower: Converts all characters in key to lower case.
  • escape: Performs URI escaping on all characters in key.
  • unescape: Translates URI escaped characters in key to the original ones.

This type of map performs a key/value lookup. The table used for lookup is defined in a plain text file specified by source. The format of the text file must be as the following:

#This line is a comment

key1  value1
key2  value2
key3  value3
keyn  valuen


This type of map performs a key/multiple_value lookup. The table used for lookup is defined in a plain text file specified by source. The main difference with type txt, is that this type of map return a randomly chosen value from a set of multiple values that are mapped to a key. The multiple values are separated by the | symbol. The format of the text file must be as the following:

#This line is a comment

key1  value11|value12|...|value1i
key2  value21|value22|...|value2j
key3  value31|value32|...|value3k
keyn  valuen1|valuen2|...|valuenx


This type of map performs a key/value lookup and it uses a hash database compatible with Apache SDBM implementation. It requires a couple of files in hash format as specified by SDBM. Those files have the same filename, but different extensions (.pag and .dir). When you define a dbm: map, you only need to specify as source the filename of the hash database without any extension. For example:

RewriteMap mymap dbm:x:\maps\mymap.db

For the map above, you need two files:

  • x:\maps\mymap.db.dir
  • x:\maps\mymap.db.pag

You can convert a plain text map file (such as the ones for txt: function) to a hash database by using the dbmtool.exe command line program provided with IIS Mod-Rewrite installation. You can also download dbmtool.exe here.


This type of map executes an external program that accepts a key as input and returns a value for that key. The script of the external program is the textfile specified by source.

prg: function uses by default the standard Windows Scripting engine. To achieve higher compatibility with Apache, you need to install a third party implementation of Perl for Windows on your system. If you want to use Perl or any other scripting engine instead of the default, you must specify the command line for the execution of the custom script engine. You can find more information about how to set a custom scripting engine at Control Center documentation.

The external program must follow a simple rule to able to work with prg: function. It must contain an infinite loop that waits for an incoming line (the key) in the stdin stream and then it writes a line (the corresponding value) to the stdout stream. The simple JScript example below shows how it works:

//JScript example map program

function Lookup( var key )
   var value;

   //Do your own lookup here

   return value;

while ( !WScript.StdIn.AtEndOfStream )
   var key = WScript.StdIn.ReadLine();
   var value = Lookup( key );
   WScript.StdOut.WriteLine( value );

RewriteMap prg: is thread safe so there is no need for process-wide synchronization. However, if you need to apply system-wide synchronization, you can add a RewriteLock directive.

Download and try
IIS Mod-Rewrite

IIS rewrite

Download IIS Mod-Rewrite

Purchase IIS Mod-Rewrite