IIS URL Rewrite Module 2
Readme
Table of Contents
IIS URL Rewrite Module 2 is an incremental release
that includes all the features from version 1.1, and adds support for outbound
response rewriting. More specifically, it can be used to:
- Implement complex URL rewriting logic by using custom rewrite providers
written in .NET.
- Replace the URLs generated by a web application in the response HTML
with a more user friendly and search engine friendly equivalent
- Modify the links in the HTML markup generated by a web application
behind a reverse proxy.
- Fix up the content of any HTTP response by using regular expression
pattern matching.
For more information on capabilities of the module refer to
IIS URL Rewrite Module
2 Overview.
IIS URL Rewrite Module 2 includes the following key features:
- Custom rewrite providers. Custom rewrite providers can
be implemented in any .NET language and can be used in cases where built-in
rewriting functionality is not sufficient.
- Rules-based response rewriting engine. Outbound rules
are used to express the logic of what to compare parts of the response with
and what to do if comparison was successful. Web server and site
administrators can use outbound rules to define complex response rewriting
logic.
- Rewriting within the content of specific HTML tags. Instead of
scanning the entire response for a particular match, the rule can be
configured to look only inside of certain HTML tags, such as <a>, <img>,
etc. That way the pattern is greatly simplified and the process of applying
the rule to the content is much faster comparing to applying the pattern to
the entire response.
- Pre-conditions for outbound rules. Applying rewrite
rules on every response is an expensive operation and is not necessary in
majority of the cases. Pre-conditions are used to check the request
metadata to determine if outbound rules evaluation should be applied.
- Setting of server variables and HTTP headers. Various
IIS server variables and HTTP request headers can be set by using rewrite
rules.
- Setting of response HTTP Headers. Outbound rewrite
rules can be used to set response HTTP headers.
- Tracking capture groups across rule conditions. The
conditions back-referencing logic in URL Rewrite 1.1 worked only against the
last matched conditions. In v2 it is possible to configure back-referencing
logic to work against all matched conditions.
- Logging of rewritten URLs. The module can be configured
to log the rewritten URL in IIS W3C logs as opposed to logging an originally
requested URL
- Updated user interface in IIS Manager. The user
interface has been significantly improved to better represent the module
configuration and to simplify such common tasks as configuring of rewrite
rules and rewrite conditions.
There are two separate downloadable packages for the module; you will need to
download the appropriate package for your version of Windows OS:
You will need to run the installation package as an administrator. This can be
accomplished by one of the following methods:
- Logging in to your server using the actual account named
"Administrator".
- Logging on using an account with administrator privileges and opening a
command-prompt by right-clicking the Command Prompt menu item that is
located in the Accessories menu for Windows programs and selecting
"Run as administrator", then typing the appropriate command listed below for
your version of Windows to run the installation:
msiexec /I <msi_filename>
Note:
- If a previous version of IIS URL Rewrite Module, such as v1.0 and v1.1,
is already installed then it will be upgraded to the version 2
- If a RC version of the IIS URL Rewrite Module 2 is already installed,
then it will be upgraded to the final RTW version.
The installation package includes several additional components and hotfixes
required by URL rewriter. Refer to the KB articles for the hotfixes to get more
details. In order to apply the hotfixes correctly without restarting the server,
it is necessary to stop WAS service and Web Management service before installing URL Rewrite
Module. To stop these services run the following command from an elevated
command prompt:
net stop was /y & net stop wmsvc
Once the module has been installed run this command:
net start w3svc & net start wmsvc
The following hotfixes may be installed with URL Rewrite Module 2:
- Update for IIS 7.0 FastCGI module (KB
954946);
- Hotfix for IIS 7.0 SetUri function (KB
949172)
- Hotfix for ASP.NET System.Web.dll (KB
957660)
Note that the hotfix for ASP.NET System.Web.dll will be installed only if
.NET Framework 3.5 SP1 is already installed on the machine. If the .NET
Framework 3.5 SP1 was installed after URL rewrite module has been installed,
then the hotfix can be applied by re-running the installer for URL Rewrite
Module in repair mode.
- Outbound rules are not applied to chunked transfer encoded responses if
rewriteBeforeCache is enabled. Set rewriteBeforeCache to false if you need
to rewrite responses that are chunked transfer encoded.
Using outbound rewriting with IIS compression
Outbound rewriting can only be applied on un-compressed responses. If the
response is already compressed then URL Rewrite Module will report an error if
any of the outbound rules is evaluated against that response.
Oubound rewriting cannot be used together with IIS static compression.
Outbound rewriting can be used together with IIS dynamic compression by using
the following workaround:
- Set the LogRewrittenUrlEnabled registry key:
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v
LogRewrittenUrlEnabled /t REG_DWORD /d 0
- Make sure that dynamicCompressionBeforeCache property
is set to false for the /system.webServer/urlCompression configuration
element.
- Re-order the IIS modules to have URL Rewrite module (RewriteModule) run
before Dynamic Compression module (DynamicCompressionModule). In the IIS
Manager user interface in the modules's ordered view the Dynamic Compression
module should be above the URL Rewrite module.
Disabling internal caching of rewrite rules
To disable caching of inbound rewrite rules in URL Rewrite Module run the
following command from an elevated command prompt:
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v RewriteCacheEnabled /t REG_DWORD /d 0
Double encoding detection
You can configure UrlDecode built-in function to fail if the input data is
double encoded by setting “DecodeAllowsDoubleEncoding” to 0 in the registry key.
Run the following command from an elevated command prompt:
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v
UrlDecodeAllowsDoubleEncoding /t REG_DWORD /d 0
Disabling inbound or outbound rewrite functionality
You can configure URL rewrite to stop applying inbound or outbound rewrite
rules. Execute the following commands:
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v
InboundRewriteEnabled /t REG_DWORD /d 0
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v
OutboundRewriteEnabled /t REG_DWORD /d 0
Disabling the logging of rewritten URLs
To prevent logging of rewritten URL's in the IIS log files use the command
below. The rewritten URLs will never be logged even if the rewrite rule is
explicitly configured to log rewritten URLs.
reg add HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\InetStp\Rewrite /v
LogRewrittenUrlEnabled /t REG_DWORD /d 0
If you encounter any problems during installation, you can run appropriate
command listed below for your version of Windows to create a log file that will
contain information about the installation process:
msiexec /L urlrewriteinstall.log /I <msi_filename>
You can analyze this log file after a failed installation to help determine
the cause of the failure.
The following additional resources for the IIS URL Rewrite Module are
available on IIS.net:
© 2010 Microsoft Corporation.