RewriteRule directive

Description: Defines URL rewriting rule
Syntax: RewriteRule Pattern Substitution [flags]
Context: server config, virtual host, directory, .htaccess

 

This directive defines a single URL rewriting operation. It may occur more that once in configuration file with each instance defining a rule to rewrite URL. RewriteRule directive consists of URL matching Pattern, Substitution string and optional set of flags.

Pattern is a perl compatible regular expression which will be matched against current URL. The current URL can be originally requested URL or URL already altered by preceding rules. URL never includes protocol or host name and starts from the first slash character (true for httpd.conf only). Also current URL differs depending on a level of configuration that is applied, i.e. for directory level configuration (.htaccess file) trailing slash and configuration file directory name will be omitted from the URL to match against. Please see Regular expression syntax section of the documentation for more information on building regular expressions.

Preceding pattern by a '!' character will negate entire expression. Negated pattern cannot generate submatches so you cannot use $N references in substitution.

Substitution string specifies format string to generate new URL if the Pattern was matched. In addition to plain text, it can include these specail characters:

  • back references to RewriteRule pattern $N
  • back references to RewriteCond patterns %N
  • server variables %{VARNAME}
  • conditional format patterns ?Ntrue_string:false_string
  • grouping parenthesis ‘(‘ and ‘)’

Substitution strings treat all characters as literals except for '$', '\', '(', ')', '?', ':' and '\'. To read special characters literally it is recommended to escape it with '\'. The following special characters are allowed:
 

$& Outputs what matched the whole expression.
$` Outputs the text between the end of the last match found (or the start of the text if no previous match was found), and the start of the current match.
$' Outputs all the text following the end of the current match.
$$ Outputs a literal '$'
\a The bell character.
\f The form feed character.
\n The newline character.
\r The carriage return character.
\t The tab character.
\v A vertical tab character.
\x A hexadecimal character - for example \x0D.
\x{} A possible unicode hexadecimal character - for example \x{1A0}
\cx The ASCII escape character x, for example \c@ is equivalent to escape-@.
\e The ASCII escape character.
\dd An octal character constant, for example \10.
\l Causes the next character to be outputted, to be output in lower case.
\u Causes the next character to be outputted, to be output in upper case.
\L Causes all subsequent characters to be output in lower case, until a \E is found.
\U Causes all subsequent characters to be output in upper case, until a \E is found.
\E Terminates a \L or \U sequence.
\\ Single back slash character '\'

RewriteRules are applied in the order of appearance in configuration file, starting from the parent configuration files. Each rule will apply only if its Pattern matches a URL and all connected conditions (RewriteCond) are also matched. After that URL is completely replaced by a Substitution and rewriting process continues until the end of configuration file or a rule with any of the stop flags. Special string '-' (dash) in Substitution means no substitution, and it is useful when you need to apply the rule while leaving original URL untouched.

Additionally here is the list of supported flags that can alter rule behavior. Fully Apache compatible flags are marked green, unsupported flags are red, and additional flags only supported by ISAPI_Rewrite are yellow. ISAPI_Rewrite will ignore all unsupported flags.

  • CU (Case Upper)

    Changes the case of substitution result to upper.
     
  • CL (Case Lower)

    Changes the case of substitution result to lower.
     
  • chain|C

    Chains current rule with the next rule. Next rule will be executed only if current rule is matched. Chain can be subsequent.
     
  • cookie|CO=NAME:VAL:domain[:lifetime[:path]]

    Sets a cookie header with the fields specified and send it to the client with the response to the current request.
     
  • env|E=VAR:VAL

    Unsupported. In UNIX environment sets an environment variable. Meaningless for Windows systems.
     
  • forbidden|F

    Sends immediate 403 FORBIDDEN response to the client. Stops rule processing and all other subsequent processing on this request.
     
  • gone|G

    Sends immediate 401 GONE response to the client. Stops rule processing and all other subsequent processing on this request.
     
  • handler|H=Content-handler

    Unsupported. Explicitly specifies handler for a request. In IIS world this can be achieved by rewriting file extension of requested file but there is no direct translation from Apache handlers to IIS file extensions.
     
  • last|L

    Stops rewrite process here and doesn’t apply any more rules from the current configuration file. Descendant .htaccess files will still be applied if any.
     
  • loop|LP

    Re-runs current single rule in the loop while it’s pattern and conditions are matched. Number of iterations is limited to a value of 200 to avoid infinite loops.
     
  • next|N

    Re-runs rewriting process starting from the beginning of current configuration file. Number of iterations is limited to a value of 200 to avoid infinite loops.
     
  • nocase|NC

    This flag makes the Pattern case-insensitive.
     
  • noescape|NE

    Don't escape output. By default ISAPI_Rewrite will encode all non-ANSI characters as %xx hex codes in output.
     
  • nosubreq|NS

    ISAPI_Rewrite meaning of this flag differs from Apache. Exact translation isn't possible, but this flag may still be useful. Every time when configuration file processing has been finished and URL has been rewritten, ISAPI_Rewrite will start processing with this new URL again (same as Apache) making it possible to apply another configuration file. This flag means that the rule should be executed only for initial user request and not for rewritten requests, to prevent possible loops. ISAPI_Rewrite limits number of loops to 10 repetitions.
     
  • O (nOrmalize)

    Leaved for compatibility with ISAPI_Rewrite 2.x. If RewriteCompatibility2 on is used, this directive normalizes URL before processing. Normalization includes removing of an URL-encoding, illegal characters, etc. Also normalization of URL completely removes query string from it. If no RewriteCompatibility2 on is used, URLs are normilized by default (as it is done in mod_rewrite) and meaning of this flag is inverted.
     
  • proxy|P

    Forces 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.
     
  • passthrough|PT

    Unsupported or always on. Result is always passed through the next handler in IIS.
     
  • qsappend|QSA

    Appends current query string data to a substitution string instead of replacing it by a substitution. Use this when you need to add more query string parameters while preserving original parameters.
     
  • redirect|R [=code]

    Forces server to send immediate response to client with redirect instruction, providing Substitution as a new location. It can optionally prefix Substitution with http://thishost[:thisport]/ bringing URL to a valid absolute form. If no code is given, a HTTP response of 302 (MOVED TEMPORARILY) will be used. You can optionally specify any code from 3xx range.
     
  • skip|S=num

    Forces the rewriting engine to skip the next num rules in sequence, if the current rule matches.
     
  • type|T=MIME-type
     
    Forces the MIME-type of the target file to be MIME-type. This can be used to set up the content-type based on some conditions.
     
  • U (Unmangle log)
     
    Unmangle log. Log the URL as it was originally requested and not as the URL was rewritten.