IIS Mod-Rewrite documentation
Overview Documentation    Quick overview    Rewrite directives    Support directives    Extended directives    Control center    Apache compatibility Download Purchase FAQ  
IIS Mod-Rewrite

Quick overview

IIS Mod-Rewrite is a URL rewriting module for Internet Information Services (IIS). The logic of URL manipulation runs on regular expression (regex) based rules.

The configuration syntax and the behavior of IIS Mod-Rewrite engine are compatible with Apache mod_rewrite, so configurations from Apache can be easily migrated to IIS and vice versa. For more information about compatibility, click here.

How it works

The URL manipulation mechanism of IIS Mod-Rewrite is rule based. When a requested URL matches a rule, a specified text substitution is performed on that URL.

Every rule is based on a regular expression. When a rule is executed, first the regex is tested on the input URL. If a match occurs, then IIS Mod-Rewrite proceeds with the substitution of the URL. The substitution text consists of a combination of static and dynamic text strings. The inserted dynamic strings can be substrings of the matched URL (backreferences), server variables, or mapped values through lookup tables. This basic mechanism can be applied for a sequence of rules. The first rule take as input the URL passed by the webserver, and each next rule takes as input the output URL of the previously matched rule.

Furthermore, a matched rule may be subject of additional conditions. If those conditions are met, then the URL substitution is applied. For more about rules, conditions, regular expressions, and text substitution, see RewriteRule and RewriteCond directives.

Finally, additional features such as logging (RewriteLog) and key/value mapping functions (RewriteMap) make IIS Mod-Rewrite a powerful, feature rich, multi-purpose tool.


The rewrite configuration is a script that forms a set of directives. This script resides in a plain text file that can be specified by using IIS Mod-Rewrite Control Center. IIS Mod-Rewrite engine checks that configuration file every 20 seconds, and every change is automatically applied.

Read more about directives.

Backreferences, server variables, and map values

In RewriteRule or RewriteCond you have two arguments. The regular expression and the substitution string (RewriteRule) or test string (RewriteCond). The substitution or test string can be a combination of static and dynamic text. The dynamic text can be the following:

  • Rule backreferences, using the symbol $N, where N can be a number from 0 to 9. A rule backreference is the Nth group "()" in the current RewriteRule's regex. Backreference $0 returns the entire matched text by RewriteRule's the regex. For more information about regex, text groups, rules, and substitution strings take a look at RewriteRule directive.
  • Condition backreferences, using the symbol %N, where N can be a number from 0 to 9. A condition backreference is the Nth group "()" in the last matched RewriteCond's regex. Backreference %0 returns the entire matched text by the RewriteCond's regex. For more information about regex, text groups, conditions, and test strings take a look at RewriteCond directive.
  • Server variables, using the symbol %{xxx}, where xxx is any server variable listed in compatibility list
  • Map value, using ${mapname:key|default}, where "mapname" is the name of the target RewriteMap, "key" the passed key to the map, and "default" is the default value returned by the map if "key" is not found. For more information about maps, take a look at RewriteMap directive.

Configuration scopes

IIS Mod-Rewrite supports four configuration scopes:
  • Per-server
  • Per-virtual-host
  • Per-directory    supported only by IIS Mod-Rewrite Pro
  • Override (htaccess)    supported only by IIS Mod-Rewrite Pro

This means you can define a global, server-wide rewrite configuration for every HTTP request accepted by the server. Also, you can define separate rewrite configurations for every virtual-host running on the server.

Optionally, you can define rewrite rules for specific parts of a website. By using a per-directory configuration you can define rewrite rules that apply only in a specific physical directory and its subdirectories (i.e. c:\Inetpub\wwwroot\pages\archive_files ).

Also, you can override a per-directory configuration by using an "Override" configuration, widely known also as ".htaccess" configuration. An override configuration resides in a separate file and is located in the target directory.

Note the input URL in per-directory and override configurations is relative to the target directory. Therefore rewrite rules in those configurations should expect relative input urls that start without a '/' prefix.

For higher portability of rewrite configurations, the configuration scope boundaries are defined as in Apache webserver's configuration file (httpd.conf).

  • Per-server configuration directives are written in the main space of the configuration script.
  • Per-virtual-host configuration directives are written only within the area that is delimited by a couple of <VirtualHost hostname1 hostname2 ... hostnameN>...</VirtualHost> tags. For each virtual host scope you can use multiple host names. hostnameN can be either a full domain name or an IP address.
  • Per-directory configuration directives are written within the area that is delimited by a couple of <Directory path>...</Directory> tags. Path can only be a full path to a file system directory (x:/physical/path)
  • Override or .htaccess configuration directives are written in a separate file. The default filename is ".htaccess" (note that ".htaccess" is not the extension of the filename but the whole filename). You can also specify a different override filename. For more information, see the Override filename section in IIS Mod-Rewrite Control Center.

Per-directory and override (.htaccess) configurations can reside either in per-server scope or within per-virtual-host scope.

Important: To allow of deny override configurations you need to use the AllowOverride directive within the related per-directory configuration. For example:

<Directory x:/TargetDirectory/SubDir>
    AllowOverride All

Configuration example:

# Server scope

RewriteEngine On
RewriteMap Upper int:toupper

RewriteLog C:\Server.log
RewriteLogLevel 2

RewriteRule ^/old_dir/(.*)$ /new_dir/($1) [R,L]
RewriteRule ^/old_stuff/(.*)$ /new_stuff/($1) [R,L]

# Virtual host scope
<VirtualHost www.host.dom host.dom>
    RewriteEngine On
    RewriteRule ^/old_pages/(.*)$ /new_pages/$1 [R]

    # Directory scope within the virtual host scope
    <Directory "C:/Inetpub/wwwroot/host/archive">
        RewriteEngine On
        RewriteRule ^/old_stuff/(.*)$ /new_stuff/$1 [R,L]
        RewriteBase /some/url/path


# Directory scope within the global scope
<Directory "C:/Inetpub/wwwroot/archive">
    RewriteEngine On
    RewriteBase /archive/

    RewriteRule ^enter/(.*)$ /exit/$1 [R,L]

Override (.htaccess) example:

#directives within the .htaccess file

RewriteEngine On
RewriteBase /archive/

RewriteRule ^enter/(.*)$ /exit/$1 [R,L]
Download and try
IIS Mod-Rewrite

IIS rewrite

Download IIS Mod-Rewrite

Purchase IIS Mod-Rewrite