ISAPI Rewrite based URL manipulation module for IIS

ISAPI_Rewrite provides a rule-based rewriting engine to rewrite requested URLs on the fly. It supports virtually unlimited number of rules and virtually unlimited number of attached rule conditions to provide really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on tests for HTTP headers, Server variables, the requested URL itself and various different conditions.

URL manipulations are established using text configuration files with set of directives inside. There are several levels of configurations. First global (server wide) configuration directives are placed in file with the name httpd.conf in the ISAPI_Rewrite installation folder. There are also several tags that can enclose directives to apply for special locations: , , , , , and . Finally ISAPI_Rewrite supports .htaccess files that can uppear in any directory inside a web site and rules from these files will apply to this location and subdirectories. All configuration files are reloaded automatically every time the file is changed. It is allowed to change file content from third party programs and scripts.

In most cases ISAPI_Rewrite is used to rewrite requested URL. In addition to rewrite ISAPI_Rewrite can modify, create or remove any other HTTP header of the client REQUEST. Module operation may lead in rewriting, proxying, redirection, or blocking of an original client request to a server.

Rewriting will cause server to continue request processing with a new URL as if it has been originally requested by a client. New URL can include query string section (following the question mark) and may point to any plain static files, scripts (like ASP), programs (like EXE), etc. within the same web application (which usually means same web site). Rewriting is completely transparent to the user and web site applications because it is done internally on a server and before web application receives request.

Proxying causes the resulting URL to be internally treated as a target on another server and immediately (i.e. rules processing stops here) passed to the remote server. Response of the remote server will then be passed back to the client. Proxy requires you to specify fully qualified URL, starting from protocol, host name, etc. ISAPI_Rewrite uses ISAPI extension to handle proxy requests. You can read more about this in configuring proxy chapter.

Redirection will result in sending of immediate response with a redirect instruction (HTTP response code 302 or 301) setting substituted URL as a new location. You can use an absolute URL format (and that is required by the RFC 2616) in redirection instruction to redirect the request to a different host, port and protocol. If this information is omitted, ISAPI_Rewrite will automatically supply URL with the current request's protocol, server name and directory location. Redirect instruction always causes rewriting engine to stop rules processing sequence.

Rules are applied in the order of appearance in configuration files. Directory level configuration files are processed file by file starting from the parents. Rules from global (server wide) configuration file are applied first. Order of rules is important because substitution result of one rule will become a source for subsequent rules application.

Before any URL modification ISAPI_Rewrite saves original URL into the HTTP header named X-Rewrite-URL. Then it can be retrieved in script as HTTP_X_REWRITE_URL server variable. Since in IIS world server variables cannot be modified ISAPI_Rewrite cannot provide this variable as REQUEST_URI for Apache compatibility. If your application is designed to rely on REQUEST_URI variable you will need to patch it to work with HTTP_X_REWRITE_URL variable instead. Here is a patch example for PHP code:

if (isset($_SERVER['HTTP_X_REWRITE_URL']))
{
$_SERVER['REQUEST_URI'] = $_SERVER['HTTP_X_REWRITE_URL'];
}

Multiple RewiteCond directives followed by RewriteRule (or RewriteProxy) directive affect only that single rule. If some condition has to be used with more than on rule, this condition directive should be repeated for every rule to apply.