Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_rewrite_module.xml @ 1061:cb63563024eb

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Somewhat clarified how rewrite module works.
author Ruslan Ermilov <ru@nginx.com>
date Sat, 08 Feb 2014 16:23:06 +0400
parents 95c3c3bbf1ce
children 4c2324a7eeea
comparison
equal deleted inserted replaced
1060:b841fbb8c577 1061:cb63563024eb
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9 9
10 <module name="Module ngx_http_rewrite_module" 10 <module name="Module ngx_http_rewrite_module"
11 link="/en/docs/http/ngx_http_rewrite_module.html" 11 link="/en/docs/http/ngx_http_rewrite_module.html"
12 lang="en" 12 lang="en"
13 rev="4"> 13 rev="5">
14 14
15 <section id="summary"> 15 <section id="summary">
16 16
17 <para> 17 <para>
18 The <literal>ngx_http_rewrite_module</literal> module is used to 18 The <literal>ngx_http_rewrite_module</literal> module is used to
19 change URIs using regular expressions, return redirects, and 19 change request URI using regular expressions, return redirects, and
20 conditionally select configurations. 20 conditionally select configurations.
21 </para> 21 </para>
22 22
23 <para> 23 <para>
24 The <literal>ngx_http_rewrite_module</literal> module directives are 24 The <literal>ngx_http_rewrite_module</literal> module directives are
25 processed in the following order: 25 processed in the following order:
26 <list type="bullet"> 26 <list type="bullet">
27 27
28 <listitem> 28 <listitem>
29 the directives of this module specified on the 29 the directives of this module specified on the
30 <link doc="ngx_http_core_module.xml" id="server"/> level are processed; 30 <link doc="ngx_http_core_module.xml" id="server"/> level
31 </listitem> 31 are executed sequentially;
32 32 </listitem>
33 <listitem> 33
34 a location for a request is searched; 34 <listitem>
35 </listitem> 35 repeatedly:
36 36 <list type="bullet">
37 <listitem> 37
38 the directives of this module specified in the selected 38 <listitem>
39 <link doc="ngx_http_core_module.xml" id="location"/> are processed. 39 a
40 If they have been changing a URI, a new location is searched for the new URI. 40 <link doc="ngx_http_core_module.xml" id="location"/>
41 This cycle may be repeated up to 41 is searched based on a request URI;
42 <link doc="ngx_http_core_module.xml" id="internal">10 times</link> 42 </listitem>
43 after which the <http-status code="500" text="Internal Server Error"/> error 43
44 is returned. 44 <listitem>
45 the directives of this module specified inside the found location
46 are executed sequentially;
47 </listitem>
48
49 <listitem>
50 the loop is repeated if a request URI was <link id="rewrite">rewritten</link>,
51 but not more than
52 <link doc="ngx_http_core_module.xml" id="internal">10 times</link>.
53 </listitem>
54
55 </list>
45 </listitem> 56 </listitem>
46 57
47 </list> 58 </list>
48 </para> 59 </para>
49 60
60 <context>if</context> 71 <context>if</context>
61 72
62 <para> 73 <para>
63 Stops processing the current set of 74 Stops processing the current set of
64 <literal>ngx_http_rewrite_module</literal> directives. 75 <literal>ngx_http_rewrite_module</literal> directives.
76 </para>
77
78 <para>
79 If a directive is specified inside the
80 <link doc="ngx_http_core_module.xml" id="location"/>,
81 further processing of the request continues in this location.
65 </para> 82 </para>
66 83
67 <para> 84 <para>
68 Example: 85 Example:
69 <example> 86 <example>
222 <note> 239 <note>
223 The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13. 240 The code 307 was not treated as a redirect until versions 1.1.16 and 1.0.13.
224 </note> 241 </note>
225 </para> 242 </para>
226 243
244 <para>
245 See also the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
246 </para>
247
227 </directive> 248 </directive>
228 249
229 250
230 <directive name="rewrite"> 251 <directive name="rewrite">
231 <syntax> 252 <syntax>
236 <context>server</context> 257 <context>server</context>
237 <context>location</context> 258 <context>location</context>
238 <context>if</context> 259 <context>if</context>
239 260
240 <para> 261 <para>
241 If the specified regular expression matches a URI, the URI is changed 262 If the specified regular expression matches a request URI, URI is changed
242 as specified in the <value>replacement</value> string. 263 as specified in the <value>replacement</value> string.
243 The <literal>rewrite</literal> directives are executed sequentially 264 The <literal>rewrite</literal> directives are executed sequentially
244 in order of their appearance in the configuration file. 265 in order of their appearance in the configuration file.
245 It is possible to terminate further processing of the directives using flags. 266 It is possible to terminate further processing of the directives using flags.
246 If a replacement string starts with “<literal>http://</literal>” 267 If a replacement string starts with “<literal>http://</literal>”
260 </tag-desc> 281 </tag-desc>
261 282
262 <tag-name><literal>break</literal></tag-name> 283 <tag-name><literal>break</literal></tag-name>
263 <tag-desc> 284 <tag-desc>
264 stops processing the current set of 285 stops processing the current set of
265 <literal>ngx_http_rewrite_module</literal> directives; 286 <literal>ngx_http_rewrite_module</literal> directives
287 as with the <link id="break"/> directive;
266 </tag-desc> 288 </tag-desc>
267 289
268 <tag-name><literal>redirect</literal></tag-name> 290 <tag-name><literal>redirect</literal></tag-name>
269 <tag-desc> 291 <tag-desc>
270 returns a temporary redirect with the 302 code; 292 returns a temporary redirect with the 302 code;
347 369
348 </directive> 370 </directive>
349 371
350 372
351 <directive name="set"> 373 <directive name="set">
352 <syntax><value>variable</value> <value>value</value></syntax> 374 <syntax><value>$variable</value> <value>value</value></syntax>
353 <default/> 375 <default/>
354 <context>server</context> 376 <context>server</context>
355 <context>location</context> 377 <context>location</context>
356 <context>if</context> 378 <context>if</context>
357 379