Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_rewrite_module.xml @ 392:5fd99d37a3e6
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> |