HttpRewriteModule

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

= Synopsis = This module makes it possible to change URI using Perl Compatible Regular Expressions (PCRE), and to redirect and select configuration depending on variables.

If the directives of this module are given at the server level, then they are carried out before the location of the request is determined. If in that selected location there are further rewrite directives, then they also are carried out. If the URI changed as a result of the execution of directives inside location, then location is again determined for the new URI.

This cycle can be repeated up to 10 times, after which Nginx returns a 500 error.

= Directives =

break


Completes the current set of rules. Continue processing within the current location block but do not process any more rewrite directives.

Example:

if ($slow) { limit_rate 10k; break; }

if


note: Before using if please see the if is evil page and consider using try_files instead.

Checks the truth of a condition. If the condition evaluates to true, then the code indicated in the curly braces is carried out and the request is processed in accordance with the configuration within the following block. The configuration inside the directive is inherited from the previous level.

The condition can be:


 * the name of a variable; false values are: empty string (, or any string starting with "0";
 * a comparison of a variable using the  and   operators;
 * pattern matching with regular expressions:
 * performs a case-sensitive match
 * performs a case-insensitive match ( matches  )
 * and  mean the opposite, "doesn't match"
 * checking for the existence of a file using the  or   operators;
 * checking for the existence of a directory using  or  ;
 * checking for the existence of a file, directory or symbolic link using  or  ;
 * checking whether a file is executable using  or.

Parts of the regular expressions can be in parentheses, whose value can then later be accessed in the  to   variables. See Extracting matches.

Examples of use:

if ($http_user_agent ~ MSIE) { rewrite ^(.*)$  /msie/$1  break; }

if ($http_cookie ~* "id=([^;] +)(?:;|$)" ) { set $id  $1; }

if ($request_method = POST ) { return 405; }

if ($slow) { limit_rate 10k; }

if ($invalid_referer) { return  403; }

if ($args ~ post=140){ rewrite ^ http://example.com/ permanent; } The value of the built-in variable  is given by the directive valid_referers.

return


This directive concludes execution of the rules and returns the status code indicated to client. It is possible to use any http return code, ranging in number from 0-999. Furthermore, nonstandard code 444 closes the connection without sending any headers.

rewrite


This directive changes URI in accordance with the regular expression and the replacement string. Directives are carried out in order of appearance in the configuration file.

Flags make it possible to end the execution of rewrite directives.

If the replacement string begins with  then the client will be redirected, and any further rewrite directives are terminated.

Flags can be any of the following:

- Note that outside location blocks, last and break are effectively the same.
 * last - completes processing of current rewrite directives and restarts the process (including rewriting) with a search for a match on the URI from all available locations.
 * break - completes processing of current rewrite directives and non-rewrite processing continues within the current location block only.
 * redirect - returns temporary redirect with code 302; it is used if the substituting line begins with
 * permanent - returns permanent redirect with code 301

Example:

rewrite ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  last; rewrite ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   last; return  403;

But if we place these directives in location, then it is necessary to replace flag "last" by "break", otherwise Nginx will hit the 10 cycle limit and return error 500:

location /download/ { rewrite ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break; rewrite ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   break; return  403; } If in the line of replacement arguments are indicated, then the rest of the request arguments are appended to them. To avoid having them appended, place a question mark as the last character:

rewrite ^/users/(.*)$  /show?user=$1? last;

Note: for curly braces( { and } ), as they are used both in regexes and for block control, to avoid conflicts, regexes with curly braces are to be enclosed with double quotes (or single quotes). For example, to rewrite URLs like: /photos/123456 to: /path/to/photos/12/1234/123456.png use the following (note the quotes enclosing the regex): rewrite "/photos/([0-9]{2})([0-9]{2})([0-9]{2})" /path/to/photos/$1/$1$2/$1$2$3.png;

If you specify a  at the end of a rewrite then Nginx will drop the original $args (arguments). When using $request_uri or $uri&$args you should specify the  at the end of the rewrite to avoid Nginx doubling the query string.

Example using $request_uri in a rewrite from www.example.com to example.com server { server_name www.example.com; rewrite ^ http://example.com$request_uri? permanent; }

Also rewrite operates only on path, not parameters. To rewrite a URL with parameters to another URL, use this instead: if ($args ~ post=100){ rewrite ^ http://example.com/new-address.html? permanent; } Note that the $args variable is not decoded, unlike URIs during location matching.

Also note that named subexpressions  should be used when accessing variables from a map using regular expressions (patterns begininng with  ) because the map runs on demand and will override   (even when named subexpressions are used in the map).

rewrite_log
When enabled, outputs information about rewrites to the error log at notice level.

set


Directive establishes value for the variable indicated. As the value it is possible to use a text, variables and their combination.

You can use set to define a new variable. Note that you can't set the value of a $http_xxx header variable.

uninitialized_variable_warn


Enables or disables logging of warnings about noninitialized variables.

= Internal implementation =

Internally, the rewrite directives are compiled at the time the configuration file is loaded into internal codes, usable during the request by the interpreter.

This interpreter is a simple stack virtual machine. For example, the directive:

location /download/ { if ($forbidden) { return  403; } if ($slow) { limit_rate 10k; } rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break; } will be compiled into this sequence:

variable $forbidden checking to zero recovery 403 completion of entire code variable $slow checking to zero checkings of regular expression copying "/" copying $1 copying "/mp3/" copying $2 copying ".mp3" completion of regular expression completion of entire sequence

Note that there is no code for directive limit_rate, since it does not refer to module ngx_http_rewrite_module. The "if" block exists in the same part of the configuration as the "location" directive.

If $slow is true, then what's inside the "if" block is evaluated, and in this configuration limit_rate it is equal to 10k.

Directive:

rewrite ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break; It is possible to reduce the sequence, if in the regular expression we include the first slash inside the parentheses:

rewrite ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break; then the sequence will appear like this:

checking regular expression copying $1 copying "/mp3/" copying $2 copying ".mp3" completion of regular expression completion of entire code

= References = Original Documentation

PCRE Man Page in Plain Text

RegexOne» Learn regular expressions with simple, interactive examples.

RegexPal — a JavaScript regular expression tester