Mod_Rewrite Documentation

Installation

Installing Mod_Rewrite.dll
IIS Configuration

IIS Configuration

mod_rewrite.ini
Global Values
RewriteRule
RewriteCond

Installation

Download and unzip the mod_rewrite.zip file any place you want. Inside the folder you will find:

- The IIS ISAPI filter (Mod_Rewrite.dll)
- The config file (mod_rewrite.ini)
- This Documentation (document.htm) and
- The test file mod_rewrite.htm.

The ISAPI filter Mod_Rewrite.dll can be placed anywhere you want. For security reasons keep it outside your website’s document root or any directory where Internet users don't have access.

The file mod_rewrite.ini should be placed in the same directory with Mod_Rewrite.dll.

Recommendation: Before you do any changes to the configuration please test the filter and the standard configuration file, copy the file mod_rewrite.htm on your website's document root, leave the mod_rewrite.ini as it is and follow the next steps.

IIS Configuration

Loading the filter on IIS.

Open the IIS manager.
Right click on the website you would like to install the URL rewrite filter.
Click on properties.

On the properties window, select the ISAPI Filter tab and click on Add.

On the filter's properties dialog type in "Mod_Rewrite"
Click on browse and browse to the location where you unzipped the Mod_Rewrite.dll file. Select it and click on ok.

After restarting the server the filter is loaded and ready to use.

Tip: On the command prompt "cmd" you can type "iisreset" to restart the web server.

mod_rewrite.ini

mod_rewrite.ini is a simple text file, you can open it with notepad or any text editor.

Global Values

Debug:
When the debug option is on "Debug 1" the filter creates a log file "mod_rewrite.txt" on the same directory where the Mod_Rewrite.dll file is located.

Note: For performance (Disk writing) this option should be turned off. "Debug 0" set Debug to 1 or 2 only in a development environment.

Reload:
The Reload options tells the filter how many times should process URLs after reloading the mod_rewrite.ini file.

This option is useful if you have your website hosted at other company and you want to make changes to the configuration without restarting the server.

Note: If you don't need this function a good reload time would be 5000 or more.

RewriteRule

RewriteRule checks for the URL sent by the browser (Input URL) and compares it with your rules in the mod_rewrite.ini. If the URL matches your configuration file it's then replaced by the output URL expression.

The RewriteRule format is:
(RewriteRule)(SPACE)(RegularExpression to match Input URL)(SPACE)(Output URL Expression)(SPACE)([options])

Possible options are, low case.
[l] = L. Last rule, if the rewriterule expression is matched and the option l is set, the filter will run this rule and stop.
[r=XXX] = Redirect, change XXX to 301 permanent redirect or 302 for temporary redirect

Example without options
RewriteRule ^/product/(.*).htm /product.asp?id=$1

With this rule an URL like /product/1010.htm it's replaced with /product.asp?id=1010

Example with options
RewriteRule ^/product/(.*).htm /product.asp?id=$1 [l]
RewriteRule ^/olddir/(.*) /newdir/$1 [r=301]

RewriteCond

RewriteCond works almost the same as RewriteRule but instead of matching URLs matches server variables like HTTP_REFERER, REMOTE_ADDR, HTTP_HOST, etc...

The RewriteCond format is:
(RewriteCond)(SPACE)(Server Variable)(SPACE)(Regular Expression to match)(SPACE)([OR|AND])

Examples:
If you want unwanted bots like email extractors to get fake email addresses you can add something like this to your mod_rewrite.ini.

RewriteCond HTTP_USER_AGENT EmailExtractor
RewriteRule ^/(.*) /fakeemails.asp

This rule will check the bot's, browser's user agent and replace any incoming URL to /fakeemails.asp

You can also build more logical conditions using the RewriteCond options AND or OR
RewriteCond HTTP_HOST site1.foo [OR]
RewriteCond HTTP_HOST site2.foo
RewriteRule ^/(.*) /$1

Notice: If you use the option OR in a rewritecond directive the next statement HAS to be a rewritecond if not, the filter will complain and won't start.
If the rewritecond doesn't have the options AND or OR set the next statement HAS to be a rewriterule directive.