Mercurial > hg > nginx-site
view xml/en/docs/http/ngx_http_rewrite_module.xml @ 2846:fdf1464e1977
Moved banner to the external file to make partial rollout possible.
An idea is to have several banners and show them with different probability
specified by split directive in the nginx.conf
author | Sergey Budnevitch <sb@waeme.net> |
---|---|
date | Tue, 10 May 2022 18:07:27 +0400 |
parents | dd78dd9e2cb7 |
children |
line wrap: on
line source
<?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>