Category: ISAPI

httpd.ini file example:

[ISAPI_Rewrite
 
# This is a comment
 
# 300 = 5 minutes
CacheClockRate 300
RepeatLimit 20
 
# Block external access to the httpd.ini and httpd.parse.errors files
RewriteRule /httpd(?:.ini|.parse.errors) / [F,I,O
 
# Block external access to the Helper ISAPI Extension
RewriteRule .*.isrwhlp / [F,I,O
 
# Some custom rules
RewriteCond Host: (.+)
RewriteRule (.*) /$1$2 [I

When ISAPI_Rewrite parses configuration file it creates error log file named httpd.parse.error in the same directory where parsed file is located. Only obvious syntax errors could be detected during parsing. Complex syntax errors and logic errors could be found only during rules execution. So, they will not be logged into the httpd.ini. It is recommend to check a new rule with the Regular Expressions Testing Tool before putting a rule into a configuration file.

UriMatchPrefix directive
Syntax: UriMatchPrefix PrefixString

The UriMatchPrefix directive defines a string that will be prepended to TestVerbs of all subsequent RewriteRule, RewriteProxy, RewriteCond URL and RewriteHeader URL directives (i.e. to all test conditions on URI). This directive is a partial analog of Apache’s RewriteBase directive. Default value for the UriMatchPrefix is empty string.

UriFormatPrefix directive
Syntax: UriFormatPrefix PrefixString

The UriFormatPrefix directive defines a string that will be prepended to FormatStrings of all subsequent RewriteRule and RewriteHeader URL directives (i.e. to all URI format strings). Default value for the UriFormatPrefix is empty string.

RewriteCond directive
Syntax: RewriteCond TestVerb CondPattern [Flags

The RewriteCond directive defines a rule condition. Precede a RewriteRule or RewriteHeader or RewriteProxy directive with one or more RewriteCond directives. Conditions affect only the next immediately following rule (RewriteRule, RewriteHeader or RewriteProxy). Thus they are effectively bound to this rule. A rule with conditions will be applied only if it will match a test string and all its bound conditions will match theirs test strings.

TestVerb 
Specifies verb that will be matched against regular expression.

TestVerb=(URL | METHOD | VERSION | HTTPHeaderName: | %ServerVariable) where:

URL - returns Request-URI of client request as described in RFC 2068 (HTTP 1.1); 
METHOD - returns HTTP method of client request (OPTIONS, GET, HEAD, POST, PUT, DELETE or TRACE); 
VERSION - returns HTTP version; 
HTTPHeaderName - returns value of the specified HTTP header. HTTPHeaderName can be any valid HTTP header name. Header names should include the trailing colon ":". If specified header does not exists in a client's request  TestVerb is treated as empty string. 
HTTPHeaderName = 
Accept:
Accept-Charset:
Accept-Encoding:
Accept-Language:
Authorization:
Cookie:
From:
Host:
If-Modified-Since:
If-Match:
If-None-Match:
If-Range:
If-Unmodified-Since:
Max-Forwards:
Proxy-Authorization:
Range:
Referer:
User-Agent:
Any-Custom-Header:

o For more information about HTTP headers and their values refer to RFC 2068.

o ServerVariable – returns value of the specified Server Variable. For examlpe, SERVER_PORT. Complete list of the server variables could be found in the IIS documentation. Variable name should be prefixed with % sign. Note that server variable names are case sensitive. So, using %https instead of %HTTPS, for example, will always result in an empty value.

CondPattern
The regular expression to match TestVerb.

[Flags
Flags is a comma-separated list of the following flags:

O (nOrmalize)
Normalizes string before processing. Normalization includes removing of an URL-encoding, illegal characters, etc. Also, IIS normalization of an URI completely removes query string. So, normalization should not be used if query string is needed. This flag may be useful with URLs and URL-encoded headers.

Technical note:

Internally all regular expressions of a rule with conditions are being joined into a single regular expression of a kind:

(?:Condition1RegExp)n(?:Condition2RegExp)n…n(?:ruleRegExp)
Then this single expression is being matched against a text string of combined headers. Missing headers and variables are considered as empty strings. Because special characters ^ and $ correspond to the beginning and the end of the combined text string (and not to the beginning and the end of an individual header string) theirs usage in a rule with conditions may result in a behavior completely different from the expected one. So, it is highly recommended to avoid usage of ^ and $ markers in rules with conditions.

RewriteRule directive
Syntax: RewriteRule Pattern FormatString [Flags

The RewriteRule directive is the real rewriting workhorse. The directive can occur more than once. Each directive defines one single rewriting rule. The definition order of these rules is important, because this order is used when applying the rules at run-time.

Pattern
Specifies regular expression that will be matched against Request-URI. See regular expression syntax section for more information.

FormatString
Specifies format string that will generate new URI. See format string syntax section for more information.

[Flags
Flags is a comma-separated list of the following flags:

I (ignore case)
Indicates that characters are matched regardless of a case. This flag affects RewriteRule directive and all corresponding RewriteCond directives.

F (Forbidden)
Stops the rewriting process and sends 404 Not Found response (Not 403 Forbidden. And this behaviour corresponds to the IIS 6 behaviour) to a client. Note that FormatString is useless in this case and could be set to any non-empty string.

L (last rule)
Stop the rewriting process here and don’t apply any more rewriting rules. Use this flag to prevent the currently rewritten URI from being rewritten further by following rules.

N (Next iteration)
Forces rewriting engine to modify rule’s target and restart rules checking from the beginning (all modifications are saved). Number of restarts is limited by the value specified in the RepeatLimit directive. If this number is exceeded N flag will be simply ignored.

NS (Next iteration of the same rule)
Works like the N flag but restarts rules processing from the same rule (i.e. forces repeat of the rule application). Maximum number of single rule iterations is given by the RepeatLimit directive. But a number of single rule repeats does not count for the global number of repeats (i.e. repeats limit for a number of iterations caused by N flag is independent of a number of repeats caused by NS).

P (force proxy)
Forces the result URI to be internally forced as a proxy request and immediately (i.e., rewriting rule processing stops here) put through the ISAPI extension that handles proxy requests. You have to make sure that the substitution string is a valid URI including protocol, host etc. or proxy will return an error.

R (explicit redirect)
Force server to send immediate response to client with redirect instruction, providing result URI as a new location. Redirect rule is always the last rule.

RP (permanent redirect)
Almost the same as the [R flag but issues 301 (moved permanently) HTTP status code instead of 302 (moved temporary).

U (Unmangle Log)
Log the URL as it was originally requested and not as the URL was rewritten.

O (nOrmalize)
Normalises string before processing. Normalisation includes removing of an URL-encoding, illegal characters, etc. Also, IIS normalisation of an URI completely removes query string. So, normalisation should not be used if query string is needed. This flag is useful with URLs and URL-encoded headers.

CL (Case Lower)
Changes case of a format result to lower.

CU (Case Upper)
Changes case of a format result to upper.

RewriteHeader directive
Syntax: RewriteHeader HeaderName Pattern FormatString [Flags

The RewriteHeader directive is more general variant of RewriteRule directive and it is designed to rewrite not only the URL part of client request, but any HTTP header. This directive can be used to rewrite, create or delete any HTTP headers, or even change method of the client request.

HeaderName
Specifies a HTTP header that will be rewritten. Possible values are the same as for the TestVerb parameter in the RewriteCond directive. Thus, RewriteRule directive is a synonym to the RewriteHeader URL Pattern Format [Flags

Pattern
Specifies regular expression that will be matched against specified header. See regular expression syntax section for more information.

FormatString
Specifies format string that will generate new header value. See format string syntax section for more information.

[Flags
Flags is a comma-separated list of the following flags:

I (ignore case)
Indicates that characters are matched regardless of a case. This flag affects RewriteHeader directive and all corresponding RewriteCond directives.

F (Forbidden)
Stops the rewriting process and sends 404 Not Found response (Not 403 Forbidden. And this behaviour corresponds to the IIS 6 behaviour) to a client. Note that FormatString is useless in this case and could be set to any non-empty string.

L (last rule)
Stop the rewriting process here and don’t apply any more rewriting rules.

N (Next iteration)
Forces rewriting engine to modify rule’s target and restart rule checking from the beginning (all modifications are saved). Number of restarts is limited by the value specified in the RepeatLimit directive. If this number is exceeded N flag will be simply ignored.

NS (Next iteration of the same rule)
Works like the N flag but restarts rules processing from the same rule (i.e. forces repeat of the rule application). Maximum number of single rule iterations is given by the RepeatLimit directive. But a number of single rule repeats does not count for the global number of repeats (i.e. repeats limit for a number of iterations caused by N flag is independent of a number of repeats caused by NS).

R (explicit redirect)
Force server to send immediate response to client with redirect instruction, providing new URI as a new location. Redirect rule is always the last rule.

RP (permanent redirect)
Almost the same as the [R flag but issues 301 (moved permanently) HTTP status code instead of 302 (moved temporary).

U (Unmangle Log)
Log the URL as it was originally requested and not as the URL was rewritten.

O (nOrmalize)
Normalises string before processing. Normalisation includes removing of an URL-encoding, illegal characters, etc. Also, IIS normalisation of an URI completely removes query string. So, normalisation should not be used if query string is needed. This flag is useful with URLs and URL-encoded headers.

CL (Case Lower)
Changes case of a format result to lower.

CU (Case Upper)
Changes case of a format result to upper.

To remove header, format string pattern should generate an empty string. For example this rule will remove user agent information from the client request:

RewriteHeader User-Agent: .* $1

And this rule will add Old-URL header to the request, providing a Request-URL as a header value:

RewriteCond URL (.*)
RewriteHeader Old-URL: ^$ $1

This last example will direct all WebDAV requests to the /webdav.asp script by changing request method:

RewriteCond METHOD OPTIONS
RewriteRule (.*) /webdav.asp?$1
RewriteHeader METHOD OPTIONS GET

Back to [Isapi Rewrite

How useful was this post?

Click on a star to rate it!

Average rating 0 / 5. Vote count: 0

No votes so far! Be the first to rate this post.