Module ngx_http_rewrite_module
The ngx_http_rewrite_module
module allows to change URIs using regular expressions, return redirects, and conditionally select configurations.
The ngx_http_rewrite_module
module directives are processed in the following order:
- the directives of this module specified on the server level are processed;
- a location for a request is searched;
- the directives of this module specified in the selected location are processed, and if they changed a URI, a new location is searched for the new URI. This cycle may be repeated up to 10 times after which the error 500 (Internal Server Error) is returned.
Directives
syntax: | break; |
default: | — |
context: | server , location , if |
Stops processing the current set of ngx_http_rewrite_module
directives.
Example:
if ($slow) { limit_rate 10k; break; }
syntax: | if ( |
default: | — |
context: | server , location |
The specified condition
is evaluated. If true, the directives of this module specified inside the braces are executed, and a request is assigned the configuration inside the if
directive. Configurations inside the if
directives are inherited from the previous configuration level.
A condition may be any of the following:
- a variable name; false if the value of a variable is an empty string or any string starting with “
0
”; - comparing a variable with a string using the “
=
” and “!=
” operators; - matching a variable against a regular expression using the “
~
” (for case-sensitive matching) and “~*
” (for case-insensitive matching) operators. Regular expressions can contain captures that are made available for later reuse in the$1
..$9
variables. Negative operators “!~
” and “!~*
” are also available. If a regular expression includes the characters “}
” or “;
”, the whole expressions should be enclosed in single or double quotes. - checking a file existence with the “
-f
” and “!-f
” operators; - checking a directory existence with the “
-d
” and “!-d
” operators; - checking a file, directory, or symbolic link existence with the “
-e
” and “!-e
” operators; - checking for an executable file with operators “
-x
” and “!-x
” operators.
Examples:
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; }
A value of the embedded variable $invalid_referer
is set by the valid_referers directive.
syntax: | return return return |
default: | — |
context: | server , location , if |
Stops processing and returns the specified code
to a client. The non-standard code 444 closes a connection without sending a response header.
Starting from version 0.8.42, it is possible to specify either the URL of redirect (for codes 301, 302, 303, and 307), or the text
of a response body (for other codes). A response body text or URL of redirect can contain variables. As a special case, a URL of redirect can be specified as a URI local to this server, in which case the full URL of redirect is formed according to the request scheme ($scheme
) and the server_name_in_redirect and port_in_redirect directives.
In addition, a URL
for temporary redirect with the code 302 can be specified as the sole parameter. Such a parameter should start with the string “http://
”, “https://
”, or “$scheme
”. A URL
can contain variables.
Only the following codes could be returned before version 0.7.51: 204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504.
The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
syntax: | rewrite |
default: | — |
context: | server , location , if |
If the specified regular expression matches a URI, the URI is changed as specified in the replacement
string. The rewrite
directives are executed sequentially in order of their appearance in the configuration file. Flags make it possible to terminate further processing of directives. If a replacement string starts with “http://
” or “https://
”, the processing stops and a redirect is returned to a client.
An optional flag
parameter can be one of:
last
- stops processing the current set of
ngx_http_rewrite_module
directives followed by a search for a new location matching the changed URI; break
- stops processing the current set of
ngx_http_rewrite_module
directives; redirect
- returns a temporary redirect with the code 302; used if a replacement string does not start with “
http://
” or “https://
”; permanent
- returns a permanent redirect with the code 301.
The full URL of redirects is formed according to the request scheme ($scheme
) and the server_name_in_redirect and port_in_redirect directives.
Example:
server { ... rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; return 403; ... }
But if these directives are put inside the “/download/
” location, the last
flag should be replaced by break
, otherwise nginx will make 10 cycles and return the error 500:
location /download/ { rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; return 403; }
If a replacement
string includes the new request arguments, the previous request arguments are appended after them. If this is undesired, putting a question mark at the end of a replacement string avoids having them appended, for example:
rewrite ^/users/(.*)$ /show?user=$1? last;
If a regular expression includes the characters “}
” or “;
”, the whole expressions should be enclosed in single or double quotes.
syntax: | rewrite_log |
default: | rewrite_log off; |
context: | http , server , location , if |
Enables or disables logging of ngx_http_rewrite_module
module directives processing results into the error_log at the notice
level.
syntax: | set |
default: | — |
context: | server , location , if |
Sets a value
for the specified variable
. A value
can contain text, variables, and their combination.
syntax: | uninitialized_variable_warn |
default: | uninitialized_variable_warn on; |
context: | http , server , location , if |
Controls whether warnings about uninitialized variables are logged.
Internal Implementation
The ngx_http_rewrite_module
module directives are compiled during the configuration stage into internal instructions that are interpreted during request processing. An interpreter is a simple virtual stack machine.
For example, the directives
location /download/ { if ($forbidden) { return 403; } if ($slow) { limit_rate 10k; } rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; }
will be translated into these instructions:
variable $forbidden check against zero return 403 end of code variable $slow check against zero match of regular expression copy "/" copy $1 copy "/mp3/" copy $2 copy ".mp3" end of regular expression end of code
Note that there are no instructions for the limit_rate directive above as it is unrelated to the ngx_http_rewrite_module
module. A separate configuration is created for the block. If the condition holds true, a request is assigned this configuration where limit_rate
equals to 10k.
The directive
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
can be made smaller by one instruction if the first slash in the regular expression is put inside the parentheses:
rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
The corresponding instructions will then look like this:
match of regular expression copy $1 copy "/mp3/" copy $2 copy ".mp3" end of regular expression end of code