IIS Mod-Rewrite documentation
Overview Documentation    Quick overview    Rewrite directives       RewriteEngine       RewriteRule       RewriteCond       RewriteMap       RewriteOptions       RewriteLog       RewriteLogLevel       RewriteBase       RewriteLock    Support directives    Extended directives    Control center    Apache compatibility Download Purchase FAQ  
IIS Mod-Rewrite - URL rewrite tool for IIS

RewriteRule Directive

RewriteRule directive is the most important directive for IIS Mod-Rewrite. It is the backbone of the rewrite configuration. It performs both of the two main operations for URL rewriting, the rule testing and the URL substitution.

This directive can occur more than once in a rewrite configuration. The order is important because RewriteRule directives are executed in the order they appear in the configuration script.

Configuration context
  • per-server configurations
  • per-virtual-host configurations
  • per-directory configurations
  • override (htaccess) configurations
Syntax

RewriteRule Pattern Substitution [options]

It requires two arguments. Pattern is the regular expression that the URL rule. If the URL matches the regular expression, it is replaced by the expanded Substitution string. Optionally, RewriteRule accepts options in a [O1,O2,..,On] format.

It is important to notice that the first RewriteRule accepts as input the initially requested URL by the HTTP client. However, the next RewriteRule directive accepts as input the result of the previous RewriteRule directive. The resulting URL is passed to the next RewriteRule, and so on...


Applying regular expression

A regular expression is a text matching pattern. In RewriteRule directive, the requested URL (or the previous RewriteRule result) is used as input for the matching pattern. The table below shows the semantics of the symbols used in a perl compatible regular expression:

Text
Symbol Description Example
. Any single character Every single character, such as a, or z, or 8, or @ etc, is matched.
[] Character class. Any single character within the square brackets. If [abc] is defined, every single character out of a, b or c is matched.
[^] Negated character class. Except every single character within the square brackets. If [^abc] is defined, every single character except from a, b or c is matched.
| Alternative. Right bound OR left bound text. If text1|text2 is defined, then both text1 and text2 are matched.
Quantifiers
Symbol Description Example
? 0 or 1 occurrences of the left bound character or grouped text. If times? is defined, then both time and times are matched.
* 0, 1 or more occurrences of the left bound character or grouped text. If 10* is defined, then all of 1, 10, 100 etc are matched.
+ 1 or more occurrences of the left bound character or grouped text. If 1+ is defined, then all of 1, 11, 111 etc are matched.
Grouping
Symbol Description Example
() Grouped text. The text or the regular expression contained in the parentheses, as a whole, is treated as the subject for matching. Also matches on grouped text are used as backreferences for substitution. If (ab?)+ is defined, then all of a, aa, aaa etc, and ab, abab, ababab etc are matched.
Anchors
Symbol Description Example
^ Start anchor. The right bound character or grouped text must occur at the beginning of the text. If ^abc.* is defined, then abcdef... is matched, but 0123abcdef... is not matched.
$ End anchor. The left bound character or grouped text must occur at the end of the text. If .*abc$ is defined, then ...abc is matched, but ...abcdef is not matched.
Escaping
Symbol Description Example
\ Escape the right bound character. If you want to match a special character, such as $, since this is normally used as the End Anchor symbol, you have to escape it (\$) to be counted as the simple dollar character.


You can also use the character '!' as the NOT symbol at the beginning of the regular expression. This is used in case you want the RewriteRule directive to perform the substitution when the input URL does NOT match the pattern.


Expanding substitution text

In case the input URL matches the pattern, RewriteRule directive substitutes the input URL with the Substitution string. However, the use of static text only is very restrictive. There are four ways to expand dynamic text within the substitution string:

Type Symbol Description
RewriteRule backreferences $N, where 0 < N < 9 A RewriteRule backreference is the matched text within a grouping '(...)' of the RewriteRule's pattern. $0 is the text match a whole, $1 is the first grouped match, $2 the second grouped match and so on.
RewriteCond backreferences %N, where 0 < N < 9 A RewriteCond backreference is the matched text within a grouping '(...)' of the last matched RewriteCond's pattern. %0 is the text match a whole, %1 is the first grouped match, %2 the second grouped match and so on.
Server variables %{VARIABLE_NAME} This returns the value of the requested variable name.
Map calls ${mapname:key|default} The map call returns the value that corresponds to the key, as defined in the RewriteMap named map_name. If the value is not found, the default value is returned.


There is a special substitution string that contains only the character '-'. This means "no substitution" will occur, and is useful for RewriteRule directives that only intend to perform the rule, but not the substitution (may force a "Forbidden" status; see below in options).


Options

There are several options that can affect the behavior of a RewriteRule directive.

chain|C
This rule is chained with next rule. If this rule does not match, the next rule or the set of consequently chained rules are skipped.
cookie|CO=NAME:VAL:DOMAIN[:LIFETIME[:PATH]]
Set cookie. Sets a HTTP "Set-Cookie:" header, with name NAME and value VAL. Also, you must specify the domain in which the cookie is effective. Optionally, you can specify the cookie's lifetime in minutes and the path that the cookie is effective.
env|E=NAME:VAL
Set environment variable. Sets an environment variable with name NAME and value VAL for the current request context, for later retrieval in the same context using %{ENV:XXX} expander. This option can be used more than once in order to specify multiple environment variables.
NOTICE: For security reasons, this option does not set the environment varible to the current thread's context. Also, ISAPI does not allow setting server variables, so the no environment variable set with this option is available to CGIs or other ISAPI extensions.
forbidden|F
Force HTTP status for the URL to be Forbidden. This is for blocking some URLs by sending a 403 - Forbidden HTTP status back to the client.
gone|G
Force HTTP status for the URL to be Gone. This is for marking some URLs as not longer existing by sending a 410 - Gone HTTP status back to the client.
last|L
This is the last rule. If the input URL matches this rule, no more rules will be applied.
next|N
Next round. Re-run the rewriting process from the beginning by applying again the first rule. However, this time the input URL is not the one originally requested by the client but the output of the last applied rule. This option should be used with care to avoid creating an infinite loop.
nocase|NC
Perform case insensitive text matching. The matching on the input URL will be performed ignoring the case of the URL text.
noescape|NE
Do not perform URI escaping on output. Some characters, such as '%', are escaped into their hexcode equivalent as required by the HTTP protocol for URI escaping. By using this option, such character remain unchanged.
proxy|P
Force proxy throughput. This option forces IIS Mod-Rewrite to pass the modified URL to the proxy extension module.
passthrough|PT
Pass through to next handler. This option forces IIS Mod-Rewrite to pass the modified URL to the next ISAPI filter.
qsappend|QSA
Append original querystring on output. With this option, when the URL is replaced, the original querystring that came with the client's request is appended rather than being replaced.
redirect|R[=code]
Force redirection. This option forces an HTTP redirection status. By default, a 302 HTTP status is forced. If code is specified, it can be any numeric redirect status code, or temp for temporary redirection (302), permanent for permanent redirection (301), or seeother (303)
skip|S=num
Skip next num rules. If the input URL matches the rule, the rewriting process skips the next num rules.
type|T=type
Force MIME type. This option forces IIS Mod-Rewrite to set the Content-Type HTTP header for the current request with value type.
 
 
Download and try
IIS Mod-Rewrite
NOW!


IIS rewrite

Download IIS Mod-Rewrite

Purchase IIS Mod-Rewrite