Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_rewrite_module.xml @ 392:5fd99d37a3e6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
English translation of ngx_http_rewrite_module.
author Ruslan Ermilov <ru@nginx.com>
date Fri, 03 Feb 2012 12:42:07 +0000
parents
children 0491cb7e874b
comparison
equal deleted inserted replaced
391:1702722eca07 392:5fd99d37a3e6
1 <?xml version="1.0"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Module ngx_http_rewrite_module"
6 link="/en/docs/http/ngx_http_rewrite_module.html"
7 lang="en">
8
9 <section id="summary">
10
11 <para>
12 The <literal>ngx_http_rewrite_module</literal> module allows to
13 change URIs using regular expressions, return redirects, and
14 conditionally select configurations.
15 </para>
16
17 <para>
18 The <literal>ngx_http_rewrite_module</literal> module directives are
19 processed in the following order:
20 <list type="bullet">
21
22 <listitem>
23 the directives of this module specified on the
24 <link doc="ngx_http_core_module.xml" id="server"/> level are processed;
25 </listitem>
26
27 <listitem>
28 a location for a request is searched;
29 </listitem>
30
31 <listitem>
32 the directives of this module specified in the selected
33 <link doc="ngx_http_core_module.xml" id="location"/> are processed,
34 and if they changed a URI, a new location is searched for the new URI.
35 This cycle may be repeated up to 10 times after which the error
36 <http-status code="500" text="Internal Server Error"/> is returned.
37 </listitem>
38
39 </list>
40 </para>
41
42 </section>
43
44
45 <section id="directives" name="Directives">
46
47 <directive name="break">
48 <syntax/>
49 <default/>
50 <context>server</context>
51 <context>location</context>
52 <context>if</context>
53
54 <para>
55 Stops processing the current set of
56 <literal>ngx_http_rewrite_module</literal> directives.
57 </para>
58
59 <para>
60 Example:
61 <example>
62 if ($slow) {
63 limit_rate 10k;
64 break;
65 }
66 </example>
67 </para>
68
69 </directive>
70
71
72 <directive name="if">
73 <syntax block="yes">(<value>condition</value>)</syntax>
74 <default/>
75 <context>server</context>
76 <context>location</context>
77
78 <para>
79 The specified <value>condition</value> is evaluated.
80 If true, the directives of this module specified inside the braces are
81 executed, and a request is assigned the configuration inside the
82 <literal>if</literal> directive.
83 Configurations inside the <literal>if</literal> directives are
84 inherited from the previous configuration level.
85 </para>
86
87 <para>
88 A condition may be any of the following:
89 <list type="bullet">
90
91 <listitem>
92 a variable name; false if the value of a variable is an empty string
93 or any string starting with “<literal>0</literal>”;
94 </listitem>
95
96 <listitem>
97 comparing a variable with a string using the
98 “<literal>=</literal>” and “<literal>!=</literal>” operators;
99 </listitem>
100
101 <listitem>
102 matching a variable against a regular expression using the
103 “<literal>~</literal>” (for case-sensitive matching) and
104 “<literal>~*</literal>” (for case-insensitive matching) operators.
105 Regular expressions can contain captures that are made available for
106 later reuse in the <var>$1</var>..<var>$9</var> variables.
107 Negative operators “<literal>!~</literal>” and “<literal>!~*</literal>”
108 are also available.
109 If a regular expression includes the characters “<literal>}</literal>”
110 or “<literal>;</literal>”, the whole expressions should be enclosed
111 in single or double quotes.
112 </listitem>
113
114 <listitem>
115 checking a file existence with the “<literal>-f</literal>” and
116 “<literal>!-f</literal>” operators;
117 </listitem>
118
119 <listitem>
120 checking a directory existence with the “<literal>-d</literal>” and
121 “<literal>!-d</literal>” operators;
122 </listitem>
123
124 <listitem>
125 checking a file, directory, or symbolic link existence with the
126 “<literal>-e</literal>” and “<literal>!-e</literal>” operators;
127 </listitem>
128
129 <listitem>
130 checking for an executable file with operators “<literal>-x</literal>”
131 and “<literal>!-x</literal>” operators.
132 </listitem>
133
134 </list>
135 </para>
136
137 <para>
138 Examples:
139 <example>
140 if ($http_user_agent ~ MSIE) {
141 rewrite ^(.*)$ /msie/$1 break;
142 }
143
144 if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
145 set $id $1;
146 }
147
148 if ($request_method = POST) {
149 return 405;
150 }
151
152 if ($slow) {
153 limit_rate 10k;
154 }
155
156 if ($invalid_referer) {
157 return 403;
158 }
159 </example>
160 <note>
161 A value of the embedded variable <var>$invalid_referer</var> is set by the
162 <link doc="ngx_http_referer_module.xml" id="valid_referers"/> directive.
163 </note>
164 </para>
165
166 </directive>
167
168
169 <directive name="return">
170 <syntax><value>code</value></syntax>
171 <default/>
172 <context>server</context>
173 <context>location</context>
174 <context>if</context>
175
176 <para>
177 Stops processing and returns the specified <value>code</value> to a client.
178 The following codes can be returned: 204, 400,
179 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
180 In addition, the non-standard code 444 closes a connection without sending
181 a response header.
182 </para>
183
184 </directive>
185
186
187 <directive name="rewrite">
188 <syntax>
189 <value>regex</value>
190 <value>replacement</value>
191 [<value>flag</value>]</syntax>
192 <default/>
193 <context>server</context>
194 <context>location</context>
195 <context>if</context>
196
197 <para>
198 If the specified regular expression matches a URI, the URI is changed
199 as specified in the <value>replacement</value> string.
200 The <literal>rewrite</literal> directives are executed sequentially
201 in order of their appearance in the configuration file.
202 Flags make it possible to terminate further processing of directives.
203 If a replacement string starts with “<literal>http://</literal>”
204 or “<literal>https://</literal>”, the processing stops and a
205 redirect is returned to a client.
206 </para>
207
208 <para>
209 An optional <value>flag</value> parameter can be one of:
210 <list type="tag">
211
212 <tag-name><literal>last</literal></tag-name>
213 <tag-desc>
214 stops processing the current set of
215 <literal>ngx_http_rewrite_module</literal> directives
216 followed by a search for a new location matching the changed URI;
217 </tag-desc>
218
219 <tag-name><literal>break</literal></tag-name>
220 <tag-desc>
221 stops processing the current set of
222 <literal>ngx_http_rewrite_module</literal> directives;
223 </tag-desc>
224
225 <tag-name><literal>redirect</literal></tag-name>
226 <tag-desc>
227 returns a temporary redirect with the code 302;
228 used if a replacement string does not start with
229 “<literal>http://</literal>” or “<literal>https://</literal>”;
230 </tag-desc>
231
232 <tag-name><literal>permanent</literal></tag-name>
233 <tag-desc>
234 returns a permanent redirect with the code 301.
235 </tag-desc>
236
237 </list>
238 </para>
239
240 <para>
241 Example:
242 <example>
243 server {
244 ...
245 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
246 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
247 return 403;
248 ...
249 }
250 </example>
251 </para>
252
253 <para>
254 But if these directives are put inside the “<literal>/download/</literal>”
255 location, the <literal>last</literal> flag should be replaced by
256 <literal>break</literal>, otherwise nginx will make 10 cycles and
257 return the error 500:
258 <example>
259 location /download/ {
260 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
261 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
262 return 403;
263 }
264 </example>
265 </para>
266
267 <para>
268 If a <value>replacement</value> string includes the new request arguments,
269 the previous request arguments are appended after them.
270 If this is undesired, putting a question mark at the end of a replacement
271 string avoids having them appended, for example:
272 <example>
273 rewrite ^/users/(.*)$ /show?user=$1? last;
274 </example>
275 </para>
276
277 <para>
278 If a regular expression includes the characters “<literal>}</literal>”
279 or “<literal>;</literal>”, the whole expressions should be enclosed
280 in single or double quotes.
281 </para>
282
283 </directive>
284
285
286 <directive name="set">
287 <syntax><value>variable</value> <value>value</value></syntax>
288 <default/>
289 <context>server</context>
290 <context>location</context>
291 <context>if</context>
292
293 <para>
294 Sets a <value>value</value> for the specified <value>variable</value>.
295 A <value>value</value> can contain text, variables, and their combination.
296 </para>
297
298 </directive>
299
300
301 <directive name="uninitialized_variable_warn">
302 <syntax><literal>on</literal> | <literal>off</literal></syntax>
303 <default>on</default>
304 <context>http</context>
305 <context>server</context>
306 <context>location</context>
307 <context>if</context>
308
309 <para>
310 Controls whether warnings about uninitialized variables are logged.
311 </para>
312
313 </directive>
314
315 </section>
316
317
318 <section id="internals" name="Internal Implementation">
319
320 <para>
321 The <literal>ngx_http_rewrite_module</literal> module directives
322 are compiled during the configuration stage into internal instructions
323 that are interpreted during request processing.
324 An interpreter is a simple virtual stack machine.
325 </para>
326
327 <para>
328 For example, the directives
329 <example>
330 location /download/ {
331 if ($forbidden) {
332 return 403;
333 }
334
335 if ($slow) {
336 limit_rate 10k;
337 }
338
339 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
340 }
341 </example>
342 will be translated into these instructions:
343 <example>
344 variable $forbidden
345 check against zero
346 return 403
347 end of code
348 variable $slow
349 check against zero
350 match of regular expression
351 copy "/"
352 copy $1
353 copy "/mp3/"
354 copy $2
355 copy ".mp3"
356 end of regular expression
357 end of code
358 </example>
359 </para>
360
361 <para>
362 Note that there are no instructions for the
363 <link doc="ngx_http_core_module.xml" id="limit_rate"/>
364 directive above as it is unrelated to the
365 <literal>ngx_http_rewrite_module</literal> module.
366 A separate configuration is created for the <link id="if"/> block.
367 If the condition holds true, a request is assigned this configuration
368 where <literal>limit_rate</literal> equals to 10k.
369 </para>
370
371 <para>
372 The directive
373 <example>
374 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
375 </example>
376 can be made smaller by one instruction if the first slash in the regular expression
377 is put inside the parentheses:
378 <example>
379 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
380 </example>
381 The corresponding instructions will then look like this:
382 <example>
383 match of regular expression
384 copy $1
385 copy "/mp3/"
386 copy $2
387 copy ".mp3"
388 end of regular expression
389 end of code
390 </example>
391 </para>
392
393 </section>
394
395 </module>