- Introduction
- Installation
- Working with ISAPI_Rewrite
- ISAPI_Rewrite directives
- Examples
- Troubleshooting
- Release notes
Basic concept
ISAPI_Rewrite provides a rule-based rewriting engine to modify requested URLs on the fly. It supports virtually unlimited number of rules and rule conditions to provide really flexible and powerful URL manipulation mechanism. URL manipulations can depend on states/values of HTTP headers, server variables, requested URL itself and many other conditions.
URL manipulations are established using text configuration files with a set of directives inside. There are several levels of configurations.
- Global (server wide) configuration directives are placed into httpd.conf configuration file located in ISAPI_Rewrite installation folder.
- Tags that can restrict the scope to be affected by the directives: <VirtualHost>, <Directory>, <DirectoryMatch>, <Files>, <FilesMatch>, <Location> and <LocationMatch> (all these tags may occur only in global config).
- Distributed .htaccess files that can appear on any directory level inside a web site. The rules from these files will be applied to this location and its subdirectories only.
All configuration files are reloaded automatically every time the file is changed. It is possible to change configuration files 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.
RewiteCond directives followed by RewriteRule (or RewriteProxy) directive affect only that single rule. If some condition has to be used for more than one rule, it (RewriteCond) should be repeated for every rule to apply.
Note for those using non-FastCGI environment!
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 code for PHP:
if (isset($_SERVER['HTTP_X_REWRITE_URL']))
{
$_SERVER['REQUEST_URI'] = $_SERVER['HTTP_X_REWRITE_URL'];
}Note that if occasionally you have ISAPI_Rewrite 2 and 3 installed together, the above patch won't work.
If you are on IIS/FastCGI web server, this fix is not needed.