nginx rewrite command spec

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.

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 a 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 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.