Importing Apache mod_rewrite Rules

by Ruslan Yakushev

Introduction

The URL Rewrite Module in IIS 7 and above provides an import feature that greatly simplifies the process of converting Apache mod_rewrite rules to IIS URL rewrite rules. In this walkthrough, you use the Import Rules feature provided in the URL Rewrite Module to import several mod_rewrite rules into an IIS configuration file. If you have not yet downloaded the URL Rewrite Module, you can do so at https://www.iis.net/downloads/microsoft/url-rewrite.

Set Up a Walkthrough Scenario

To see how you can convert mod_rewrite rules and verify that the converted rules work correctly, you will implement the common scenario of enforcing canonical host names for a Web site. In this example, you will force the use of www.mysite.com instead of mysite.com, so that when a request is made that uses a host name other than www.mysite.com, you can redirect the request to a canonical hostname.

  1. Start IIS Manager, and then click Default Web Site.

  2. In the Actions pane, click on Bindings, and add a new http binding for port 8088.

    Screenshot of the Site Bindings dialog after clicking Bindings under Edit Site in the Actions pane. Figure 1: Add a new binding

  3. Using Notepad, open %SystemDrive%\windows\system32\drivers\etc\hosts and add the two following lines at the end of the file:

    127.0.0.1 www_mysite_com
    127.0.0.1 mysite_com
    

    Notice that you are using "_" instead of "." for domain separators. This is to prevent the Web browser from trying to resolve the domain name by using a Domain Name System (DNS) server.

  4. Save the hosts file.

  5. Verify that the host names were setup correctly by opening a Web browser and going to the sites http://www_mysite_com/iisstart.htm and to http://mysite_com/iisstart.htm.

Convert mod_rewrite Rules

The Apache mod_rewrite rules to use for enforcing canonical host names are:

#For sites running on a port other than 80:
RewriteCond %{HTTP_HOST}   !^www_mysite_com [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteCond %{SERVER_PORT} !^80$
RewriteRule ^/(.*)         http://www_mysite_com:%{SERVER_PORT}/$1 [L,R]

#And for a site running on port 80
RewriteCond %{HTTP_HOST}   !^www_mysite_com [NC]
RewriteCond %{HTTP_HOST}   !^$
RewriteRule ^/(.*)         http://www_mysite_com/$1 [L,R]

To convert these rules to IIS URL rewrite–specific format:

  1. Start IIS Manager.

  2. On the left, in the Connections pane, select Default Web Site.

  3. On the right, in Features View, click URL Rewrite.

    Screenshot of the Default Web Site Home pane with U R L Rewrite selected.

    Figure 2: Click URL Rewrite

  4. On the right, in the Actions pane, click Import Rules.

  5. Copy the example mod_rewrite rules above and paste them into the Rewrite rules text box.

    Screenshot of the Import mod underscore rewrite Rules pane with a set of Rewrite rules and a set of successfully Converted rules.

    Figure 3: Rules to import

  6. The Tree View tab of the Converted Rules box instantly shows the result of the conversion. You can also click the XML View tab to see how the rules are stored in the Web.config file.

    Screenshot of toggling between Tree View and X M L View in the Converted rules section.

    Figure 4: Converted rules

    If you switch back to Tree View and select a node there, the corresponding mod_rewrite rule directive in the Rewrite rules text box will be highlighted.

    Screenshot of a selected node in Tree View of the Converted rules.

    Figure 5: Tree view

    Note that during the rules conversion the rules were assigned default names. To change the default names to something more meaningful, select a rule in Tree View, right-click it, and select Rename from the context menu.

    Screenshot of right-clicking a Converted rule to Rename the rule.

    Figure 6: Rename

    Change the name of the first rule from ImportedRule1 to Redirect to www_mysite_com:non-80. Change the name of the second rule from ImportedRule2 to Redirect to www_mysite_com:80.

    In the Actions pane, click Apply to save the converted rules to the Web.config file, and then click Back to rules.

    Screenshot of the Actions pane with Apply, Cancel, and Back to Rules emphasized.

    Figure 7: Back to Rules

Test the Converted Rules

To test that the rules imported from mod_rewrite format work correctly, open a Web browser, and go to either one of the following URLs:

  • http://localhost/iisstart.htm
  • http://mysite_com/iisstart.htm

In both cases, the Web browser is redirected to http://www_mysite_com/iisstart.htm.

Also, if you try either of these URLs:

  • http://localhost:8088/iisstart.htm
  • http://mysite_com:8088/iisstart.htm

the Web browser gets redirected to http://www_mysite_com:8088/iisstart.htm.

Note that the rules that were imported from mod_rewrite enabled the enforcement of canonical host names for a Web site. A Bing search will reveal other examples of Apache mod_rewrite rules.

Disclaimer

IMPORTANT - The URL Rewrite Module tries to convert Apache mod_rewrite rules to functionally equivalent IIS URL rewrite rules. However, not all mod_rewrite rules can be converted because of architectural differences between Apache and IIS. It is highly recommended that you study a mod_rewrite rule set until you understand its functionality before you begin the conversion process. Then, after converting to IIS URL rewrite rules, review and test the result of the conversion to make sure that the corresponding IIS rewrite rule set provides the same URL rewriting logic.

Note that only rules that follow Apache mod_rewrite syntax can be converted. Any other formats of rewrite rules (for example, ISAPI_Rewrite, Ionic ISAPI Rewrite, IISRewrite, and others) are not recognized or will be converted incorrectly.