ngx_http_rewrite_module
This module makes it possible to change URI using regular expressions, 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
syntax: break
default: none
context: server, location, if
Completes the current set of rules. Do not process any more rewrite directives.
Example:
if ($slow) {
limit_rate 10k;
break;
}
if
syntax: if (condition) { ... }
default: none
context: server, location
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. Configuration inside directive if is inherited from the previous level.
They can be assigned as the condition:
- the name of variable; false values are: empty string "", or any string starting with "0";
the comparison of variable with the line with using the = and != operators;
pattern matching with regular expressions using the symbols ~* and ~:
~ is case-sensitive match
~* specifies a case-insensitive match (firefox matches FireFox)
!~ and !~* mean the opposite, "doesn't match"
checking for the existence of a file using the -f and !-f operators;
checking existence of a directory using the -d and !-d operators;
checking existence of a file, directory or symbolic link using the -e and !-e operators;
checking whether a file is executable using the -x and !-x operators.
Parts of the regular expressions can be in parentheses, whose value can then later be accessed in the $1 to $9 variables.
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 (!-f $request_filename) {
break;
proxy_pass http://127.0.0.1;
}
if ($slow) {
limit_rate 10k;
}
if ($invalid_referer) {
return 403;
}
The value of the built-in variable $invalid_referer is given by the directive valid_referers.
return
syntax: return code
default: none
context: server, location, if
This directive concludes execution of the rules and returns the status code indicated to client. It is possible to use the following values: 204, 400, 402-406, 408, 410, 411, 413, 416 and 500-504. Furthermore, nonstandard code 444 closes the connection without sending any headers.
rewrite
syntax: rewrite regex replacement flag
default: none
context: server, location, if
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.
Be aware that the rewrite regex only matches the relative path instead of the absolute URL. If you want to match the hostname, you should use an if condition, like so:
#rewrites http://www.mydomain.nl/foo => http://mydomain.nl/foo
if ($host ~* www\.(.*)) {
set $host_without_www $1;
rewrite ^(.*)$ http://$host_without_www$1 permanent; # $1 contains '/foo', not 'www.mydomain.com/foo'
}
Flags make it possible to end the execution of rewrite directives.
If the replacement string begins with http:// then the client will be redirected, and any further rewrite directives are terminated.
Flags can be any of the following:
- last - completes processing of rewrite directives, after which searches for corresponding URI and location
- break - completes processing of rewrite directives
redirect - returns temporary redirect with code 302; it is used if the substituting line begins with http://
- permanent - returns permanent redirect with code 301
Note that if an redirect is relative (has no host part), then when redirecting Nginx uses the "Host" header if the header match name of server_name directive or the first name of server_name directive, if the header does not match or is absent. If no server_name is set, then the local hostname is used. If you want Nginx to always use the "Host" header, you can use a wildcard "*" server_name (but see the restrictions on doing so).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 /download/, 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 regex and for block control, to avoid conflicts, regex with curly braces are to be enclosed with double quotes (or single quotes). For example, to rewrite url's like:
/photos/123456
to:
/path/to/photos/12/1234/123456.png
use the following (note the qoutes enclosing the regex):
rewrite "/photos/([0-9]{2})([0-9]{2})([0-9]{2})" /path/to/photos/$1/$1$2/$1$2$3.png;
set
syntax: set variable value
default: none
context: server, location, if
Directive establishes value for the variable indicated. As the value it is possible to use a text, variables and their combination.
uninitialized_variable_warn
syntax: uninitialized_variable_warn on|off
default: uninitialized_variable_warn on
context: http, server, location, if
Enables or disables logging of warnings about noninitialized variables.
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 "..mpe"
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 "..mpe"
completion of regular expression
completion of entire code