ngx_http_rewrite_module.xml

<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Module ngx_http_rewrite_module"
        link="/en/docs/http/ngx_http_rewrite_module.html"
        lang="en"
        rev="9">

<section id="summary">

<para>
The <literal>ngx_http_rewrite_module</literal> module is used to
change request URI using PCRE regular expressions, return redirects, and
conditionally select configurations.
</para>

<para>
The <link id="break"/>, <link id="if"/>, <link id="return"/>,
<link id="rewrite"/>, and <link id="set"/> directives are
processed in the following order:
<list type="bullet">

<listitem>
the directives of this module specified on the
<link doc="ngx_http_core_module.xml" id="server"/> level
are executed sequentially;
</listitem>

<listitem>
repeatedly:
<list type="bullet">

<listitem>
a
<link doc="ngx_http_core_module.xml" id="location"/>
is searched based on a request URI;
</listitem>

<listitem>
the directives of this module specified inside the found location
are executed sequentially;
</listitem>

<listitem>
the loop is repeated if a request URI was <link id="rewrite">rewritten</link>,
but not more than
<link doc="ngx_http_core_module.xml" id="internal">10 times</link>.
</listitem>

</list>
</listitem>

</list>
</para>

</section>


<section id="directives" name="Directives">

<directive name="break">
<syntax/>
<default/>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Stops processing the current set of
<literal>ngx_http_rewrite_module</literal> directives.
</para>

<para>
If a directive is specified inside the
<link doc="ngx_http_core_module.xml" id="location"/>,
further processing of the request continues in this location.
</para>

<para>
Example:
<example>
if ($slow) {
    limit_rate 10k;
    break;
}
</example>
</para>

</directive>


<directive name="if">
<syntax block="yes">(<value>condition</value>)</syntax>
<default/>
<context>server</context>
<context>location</context>

<para>
The specified <value>condition</value> is evaluated.
If true, this module directives specified inside the braces are
executed, and the request is assigned the configuration inside the
<literal>if</literal> directive.
Configurations inside the <literal>if</literal> directives are
inherited from the previous configuration level.
</para>

<para>
A condition may be any of the following:
<list type="bullet">

<listitem>
a variable name; false if the value of a variable is an empty string
or “<literal>0</literal>”;
<note>
Before version 1.0.1, any string starting with “<literal>0</literal>”
was considered a false value.
</note>
</listitem>

<listitem>
comparison of a variable with a string using the
“<literal>=</literal>” and “<literal>!=</literal>” operators;
</listitem>

<listitem>
matching of a variable against a regular expression using the
“<literal>~</literal>” (for case-sensitive matching) and
“<literal>~*</literal>” (for case-insensitive matching) operators.
Regular expressions can contain captures that are made available for
later reuse in the <var>$1</var>..<var>$9</var> variables.
Negative operators “<literal>!~</literal>” and “<literal>!~*</literal>”
are also available.
If a regular expression includes the “<literal>}</literal>”
or “<literal>;</literal>” characters, the whole expressions should be enclosed
in single or double quotes.
</listitem>

<listitem>
checking of a file existence with the “<literal>-f</literal>” and
“<literal>!-f</literal>” operators;
</listitem>

<listitem>
checking of a directory existence with the “<literal>-d</literal>” and
“<literal>!-d</literal>” operators;
</listitem>

<listitem>
checking of a file, directory, or symbolic link existence with the
“<literal>-e</literal>” and “<literal>!-e</literal>” operators;
</listitem>

<listitem>
checking for an executable file with the “<literal>-x</literal>”
and “<literal>!-x</literal>” operators.
</listitem>

</list>
</para>

<para>
Examples:
<example>
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;
}
</example>
<note>
A value of the <var>$invalid_referer</var> embedded variable is set by the
<link doc="ngx_http_referer_module.xml" id="valid_referers"/> directive.
</note>
</para>

</directive>


<directive name="return">
<syntax><value>code</value> [<value>text</value>]</syntax>
<syntax><value>code</value> <value>URL</value></syntax>
<syntax><value>URL</value></syntax>
<default/>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Stops processing and returns the specified <value>code</value> to a client.
The non-standard code 444 closes a connection without sending
a response header.
</para>

<para>
Starting from version 0.8.42, it is possible to specify
either a redirect URL (for codes 301, 302, 303, 307, and 308)
or the response body <value>text</value> (for other codes).
A response body text and redirect URL can contain variables.
As a special case, a redirect URL can be specified as a URI
local to this server, in which case the full redirect URL
is formed according to the request scheme (<var>$scheme</var>) and the
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> and
<link doc="ngx_http_core_module.xml" id="port_in_redirect"/> directives.
</para>

<para>
In addition, a <value>URL</value> for temporary redirect with the code 302
can be specified as the sole parameter.
Such a parameter should start with the “<literal>http://</literal>”,
“<literal>https://</literal>”, or “<literal>$scheme</literal>” string.
A <value>URL</value> can contain variables.
</para>

<para>
<note>
Only the following codes could be returned before version 0.7.51:
204, 400, 402 — 406, 408, 410, 411, 413, 416, and 500 — 504.
</note>

<note>
The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
</note>

<note>
The code 308 was not treated as a redirect until version 1.13.0.
</note>
</para>

<para>
See also the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
</para>

</directive>


<directive name="rewrite">
<syntax>
    <value>regex</value>
    <value>replacement</value>
    [<value>flag</value>]</syntax>
<default/>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
If the specified regular expression matches a request URI, URI is changed
as specified in the <value>replacement</value> string.
The <literal>rewrite</literal> directives are executed sequentially
in order of their appearance in the configuration file.
It is possible to terminate further processing of the directives using flags.
If a replacement string starts with “<literal>http://</literal>”,
“<literal>https://</literal>”, or “<literal>$scheme</literal>”,
the processing stops and the redirect is returned to a client.
</para>

<para>
An optional <value>flag</value> parameter can be one of:
<list type="tag">

<tag-name><literal>last</literal></tag-name>
<tag-desc>
stops processing the current set of
<literal>ngx_http_rewrite_module</literal> directives and starts
a search for a new location matching the changed URI;
</tag-desc>

<tag-name><literal>break</literal></tag-name>
<tag-desc>
stops processing the current set of
<literal>ngx_http_rewrite_module</literal> directives
as with the <link id="break"/> directive;
</tag-desc>

<tag-name><literal>redirect</literal></tag-name>
<tag-desc>
returns a temporary redirect with the 302 code;
used if a replacement string does not start with
“<literal>http://</literal>”, “<literal>https://</literal>”,
or “<literal>$scheme</literal>”;
</tag-desc>

<tag-name><literal>permanent</literal></tag-name>
<tag-desc>
returns a permanent redirect with the 301 code.
</tag-desc>

</list>
The full redirect URL is formed according to the
request scheme (<var>$scheme</var>) and the
<link doc="ngx_http_core_module.xml" id="server_name_in_redirect"/> and
<link doc="ngx_http_core_module.xml" id="port_in_redirect"/> directives.
</para>

<para>
Example:
<example>
server {
    ...
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
    return  403;
    ...
}
</example>
</para>

<para>
But if these directives are put inside the “<literal>/download/</literal>”
location, the <literal>last</literal> flag should be replaced by
<literal>break</literal>, or otherwise nginx will make 10 cycles and
return the 500 error:
<example>
location /download/ {
    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
    return  403;
}
</example>
</para>

<para>
If a <value>replacement</value> 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:
<example>
rewrite ^/users/(.*)$ /show?user=$1? last;
</example>
</para>

<para>
If a regular expression includes the “<literal>}</literal>”
or “<literal>;</literal>” characters, the whole expressions should be enclosed
in single or double quotes.
</para>

</directive>


<directive name="rewrite_log">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Enables or disables logging of <literal>ngx_http_rewrite_module</literal>
module directives processing results
into the <link doc="../ngx_core_module.xml" id="error_log"/> at
the <literal>notice</literal> level.
</para>

</directive>


<directive name="set">
<syntax><value>$variable</value> <value>value</value></syntax>
<default/>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Sets a <value>value</value> for the specified <value>variable</value>.
The <value>value</value> can contain text, variables, and their combination.
</para>

</directive>


<directive name="uninitialized_variable_warn">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<context>if</context>

<para>
Controls whether warnings about uninitialized variables are logged.
</para>

</directive>

</section>


<section id="internals" name="Internal Implementation">

<para>
The <literal>ngx_http_rewrite_module</literal> module directives
are compiled at the configuration stage into internal instructions
that are interpreted during request processing.
An interpreter is a simple virtual stack machine.
</para>

<para>
For example, the directives
<example>
location /download/ {
    if ($forbidden) {
        return 403;
    }

    if ($slow) {
        limit_rate 10k;
    }

    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
}
</example>
will be translated into these instructions:
<example>
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
</example>
</para>

<para>
Note that there are no instructions for the
<link doc="ngx_http_core_module.xml" id="limit_rate"/>
directive above as it is unrelated to the
<literal>ngx_http_rewrite_module</literal> module.
A separate configuration is created for the <link id="if"/> block.
If the condition holds true, a request is assigned this configuration
where <literal>limit_rate</literal> equals to 10k.
</para>

<para>
The directive
<example>
rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
</example>
can be made smaller by one instruction if the first slash in the regular expression
is put inside the parentheses:
<example>
rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
</example>
The corresponding instructions will then look like this:
<example>
match of regular expression
copy $1
copy "/mp3/"
copy $2
copy ".mp3"
end of regular expression
end of code
</example>
</para>

</section>

</module>