Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_rewrite_module.xml @ 382:b838f6e9192e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Revision.
author Ruslan Ermilov <ru@nginx.com>
date Tue, 31 Jan 2012 16:29:31 +0000
parents 4c6d2c614d2c
children 1702722eca07
comparison
equal deleted inserted replaced
381:8ad9df891e23 382:b838f6e9192e
1 <?xml version="1.0"?> 1 <?xml version="1.0"?>
2 2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> 3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4 4
5 <module name="Директивы модуля ngx_http_rewrite_module" 5 <module name="Модуль ngx_http_rewrite_module"
6 link="/ru/docs/http/ngx_http_rewrite_module.html" 6 link="/ru/docs/http/ngx_http_rewrite_module.html"
7 lang="ru"> 7 lang="ru">
8 8
9 <section id="summary"> 9 <section id="summary">
10 10
11 <para> 11 <para>
12 Модуль ngx_http_rewrite_module позволяет изменять URI с помощью 12 Модуль <literal>ngx_http_rewrite_module</literal> позволяет
13 регулярных выражений, делать перенаправления и выбирать конфигурацию 13 изменять URI с помощью регулярных выражений, делать перенаправления
14 в зависимости от переменных. Если директивы этого модуля описаны 14 и выбирать конфигурацию в зависимости от переменных.
15 на уровне сервера, то они выполняются до того, как определяется 15 Если директивы этого модуля описаны на уровне сервера, то они
16 location для запроса. Если в выбранном location тоже есть 16 выполняются до того, как определяется location для запроса.
17 директивы модуля ngx_http_rewrite_module, то они также выполняются. 17 Если в выбранном location тоже есть директивы модуля
18 <literal>ngx_http_rewrite_module</literal>, то они также выполняются.
18 Если URI изменился в результате исполнения директив внутри location, 19 Если URI изменился в результате исполнения директив внутри location,
19 то снова определяется location для уже нового URI. Этот цикл может 20 то снова определяется location для уже нового URI.
20 повторяться до 10 раз, после чего nginx возвращает ошибку 21 Этот цикл может повторяться до 10 раз, после чего nginx возвращает
21 "Server Internal Error" (500). 22 ошибку <http-status code="500" text="Internal Server Error"/>.
22 </para> 23 </para>
23 24
24 </section> 25 </section>
25 26
26 27
27 <section name="Директивы" id="directives"> 28 <section id="directives" name="Директивы">
28 29
29 <directive name="break"> 30 <directive name="break">
30 <syntax/> 31 <syntax/>
31 <default/> 32 <default/>
32 <context>server, location, if</context> 33 <context>server</context>
33 34 <context>location</context>
34 <para> 35 <context>if</context>
35 Директива завершает обработку текущего набора директив 36
36 ngx_http_rewrite_module. 37 <para>
37 </para> 38 Завершает обработку текущего набора директив модуля
38 39 <literal>ngx_http_rewrite_module</literal>.
39 <para> 40 </para>
40 Пример использования: 41
41 <example> 42 <para>
42 if ($slow) { 43 Пример:
43 limit_rate 10k; 44 <example>
44 break; 45 if ($slow) {
45 } 46 limit_rate 10k;
47 break;
48 }
46 </example> 49 </example>
47 </para> 50 </para>
48 51
49 </directive> 52 </directive>
50 53
51 54
52 <directive name="if"> 55 <directive name="if">
53 <syntax block="yes">(<value>условие</value>)</syntax> 56 <syntax block="yes">(<value>условие</value>)</syntax>
54 <default/> 57 <default/>
55 <context>server, location</context> 58 <context>server</context>
56 59 <context>location</context>
57 <para> 60
58 Директива if проверяет истинность условия, если оно истинно, 61 <para>
62 Проверяет истинность условия.
63 Если оно истинно,
59 то выполняется указанный в фигурных скобках код и запрос обрабатывается 64 то выполняется указанный в фигурных скобках код и запрос обрабатывается
60 в соответствии с заданной там же конфигурацией. 65 в соответствии с заданной там же конфигурацией.
61 Конфигурация внутри директивы if наследуется из предыдущего уровня. 66 Конфигурация внутри директивы <literal>if</literal> наследуется с
67 предыдущего уровня.
62 </para> 68 </para>
63 69
64 <para> 70 <para>
65 В качестве условия могут быть заданы: 71 В качестве условия могут быть заданы:
66 <list type="bullet"> 72 <list type="bullet">
67 73
68 <listitem> 74 <listitem>
69 имя переменной; ложными значениями переменной являются пустая строка "" 75 имя переменной; ложными значениями переменной являются пустая строка “”
70 или любая строка, начинающиеся на "0"; 76 или любая строка, начинающаяся на “<literal>0</literal>”;
71 </listitem> 77 </listitem>
72 78
73 <listitem> 79 <listitem>
74 сравнение переменной со строкой с помощью операторов "=" и "!="; 80 сравнение переменной со строкой с помощью операторов
75 </listitem> 81 “<literal>=</literal>” и “<literal>!=</literal>”;
76 82 </listitem>
77 <listitem> 83
78 проверка переменной с помощью регулярного выражения без учёта 84 <listitem>
79 регистра символов — "~*" и с учётом — "~". 85 проверка переменной с помощью регулярного выражения с учётом
86 регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”.
80 В регулярных выражениях можно использовать выделения, которые затем 87 В регулярных выражениях можно использовать выделения, которые затем
81 доступны в виде переменных $1 — $9. 88 доступны в виде переменных <var>$1</var> — <var>$9</var>.
82 Также можно использовать отрицательные операторы "!~" и "!~*". 89 Также можно использовать отрицательные операторы “<literal>!~</literal>”
83 Если в регулярном выражении встречаются символы "}" или ";", то 90 и “<literal>!~*</literal>”.
84 всё выражение нужно заключить в одинарные или двойные кавычки. 91 Если в регулярном выражении встречаются символы “<literal>}</literal>”
85 </listitem> 92 или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные
86 93 или двойные кавычки.
87 <listitem> 94 </listitem>
88 проверка существования файла с помощью операторов "-f" и "!-f"; 95
89 </listitem> 96 <listitem>
90 97 проверка существования файла с помощью операторов “<literal>-f</literal>”
91 <listitem> 98 и “<literal>!-f</literal>”;
92 проверка существования каталога с помощью операторов "-d" и "!-d"; 99 </listitem>
100
101 <listitem>
102 проверка существования каталога с помощью операторов “<literal>-d</literal>”
103 и “<literal>!-d</literal>”;
93 </listitem> 104 </listitem>
94 105
95 <listitem> 106 <listitem>
96 проверка существования файла, каталога или символической ссылки 107 проверка существования файла, каталога или символической ссылки
97 с помощью операторов "-e" и "!-e"; 108 с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”;
98 </listitem> 109 </listitem>
99 110
100 <listitem> 111 <listitem>
101 проверка исполняемости файла с помощью операторов "-x" и "!-x". 112 проверка исполняемости файла с помощью операторов “<literal>-x</literal>”
113 и “<literal>!-x</literal>”.
102 </listitem> 114 </listitem>
103 115
104 </list> 116 </list>
105 </para> 117 </para>
106 118
107 <para> 119 <para>
108 Примеры использования: 120 Примеры:
109 <example> 121 <example>
110 if ($http_user_agent ~ MSIE) { 122 if ($http_user_agent ~ MSIE) {
111 rewrite ^(.*)$ /msie/$1 break; 123 rewrite ^(.*)$ /msie/$1 break;
112 } 124 }
113 125
114 if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) { 126 if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
115 set $id $1; 127 set $id $1;
116 } 128 }
117 129
118 if ($request_method = POST ) { 130 if ($request_method = POST) {
119 return 405; 131 return 405;
120 } 132 }
121 133
122 134
123 if ($slow) { 135 if ($slow) {
124 limit_rate 10k; 136 limit_rate 10k;
125 } 137 }
126 138
127 if ($invalid_referer) { 139 if ($invalid_referer) {
128 return 403; 140 return 403;
129 } 141 }
130 </example> 142 </example>
131 Значение встроенной переменной $invalid_referer задаётся директивой 143 Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой
132 <link doc="ngx_http_referer_module.xml" id="valid_referers"/>. 144 <link doc="ngx_http_referer_module.xml" id="valid_referers"/>.
133 </para> 145 </para>
134 146
135 </directive> 147 </directive>
136 148
137 149
138 <directive name="return"> 150 <directive name="return">
139 <syntax><value>код</value></syntax> 151 <syntax><value>код</value></syntax>
140 <default/> 152 <default/>
141 <context>server, location, if</context> 153 <context>server</context>
142 154 <context>location</context>
143 <para> 155 <context>if</context>
144 Директива return завершает исполнение кода и возвращает клиенту 156
145 указанный код. Можно использовать следующие значения: 204, 400, 157 <para>
158 Завершает исполнение кода и возвращает клиенту указанный код.
159 Можно использовать следующие значения: 204, 400,
146 402 — 406, 408, 410, 411, 413, 416 и 500 — 504. 160 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
147 Кроме того, нестандартный код 444 закрывает соединение без передачи 161 Кроме того, нестандартный код 444 закрывает соединение без передачи
148 заголовка ответа. 162 заголовка ответа.
149 </para> 163 </para>
150 164
151 </directive> 165 </directive>
152 166
153 167
154 <directive name="rewrite"> 168 <directive name="rewrite">
155 <syntax><value>regex</value> <value>замена</value> <value>флаг</value></syntax> 169 <syntax>
156 <default/> 170 <value>regex</value>
157 <context>server, location, if</context> 171 <value>замена</value>
158 172 [<value>флаг</value>]</syntax>
159 <para> 173 <default/>
160 Директива rewrite изменяет URI в соответствии с регулярным выражением 174 <context>server</context>
161 и строкой замены. Директивы выполняются в порядке их следования в 175 <context>location</context>
162 конфигурационном файле. С помощью флагов можно досрочно прекратить 176 <context>if</context>
163 исполнение директив. Если строка замены начинается с "http://", то 177
164 клиенту будет возвращено перенаправление и обработка директив также завершается. 178 <para>
179 Изменяет URI в соответствии с регулярным выражением и строкой замены.
180 Директивы выполняются в порядке их следования в конфигурационном файле.
181 С помощью флагов можно досрочно прекратить исполнение директив.
182 Если строка замены начинается с “<literal>http://</literal>”, то клиенту
183 будет возвращено перенаправление и обработка директив также завершается.
165 </para> 184 </para>
166 185
167 <para> 186 <para>
168 Флаги могут быть следующими: 187 Флаги могут быть следующими:
169 <list type="bullet"> 188 <list type="tag">
170 189
171 <listitem> 190 <tag-name><literal>last</literal></tag-name>
172 last — завершает обработку текущего набора директив 191 <tag-desc>
173 ngx_http_rewrite_module, после чего ищется соответствие URI и location; 192 завершает обработку текущего набора директив модуля
174 </listitem> 193 <literal>ngx_http_rewrite_module</literal>,
175 194 после чего ищется соответствие URI и location;
176 <listitem> 195 </tag-desc>
177 break — завершает обработку текущего набора директив 196
178 ngx_http_rewrite_module; 197 <tag-name><literal>break</literal></tag-name>
179 </listitem> 198 <tag-desc>
180 199 завершает обработку текущего набора директив модуля
181 <listitem> 200 <literal>ngx_http_rewrite_module</literal>;
182 redirect — возвращает временное перенаправление с кодом 302; 201 </tag-desc>
183 используется, если заменяющая строка не начинается с "http://"; 202
184 </listitem> 203 <tag-name><literal>redirect</literal></tag-name>
185 204 <tag-desc>
186 <listitem> 205 возвращает временное перенаправление с кодом 302;
187 permanent — возвращает постоянное перенаправление с кодом 301. 206 используется, если заменяющая строка не начинается с
188 </listitem> 207 “<literal>http://</literal>”;
208 </tag-desc>
209
210 <tag-name><literal>permanent</literal></tag-name>
211 <tag-desc>
212 возвращает постоянное перенаправление с кодом 301.
213 </tag-desc>
189 214
190 </list> 215 </list>
191 </para> 216 </para>
192 217
193 <para> 218 <para>
194 </para> 219 Пример:
195 220 <example>
196 <para> 221 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
197 Пример использования: 222 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
198 <example> 223 return 403;
199 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; 224 </example>
200 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; 225 </para>
201 return 403; 226
202 </example> 227 <para>
203 </para> 228 Если же эти директивы поместить в location “<literal>/download/</literal>”,
204 229 то нужно заменить флаг <literal>last</literal> на <literal>break</literal>,
205 <para> 230 иначе nginx сделает 10 циклов и вернёт ошибку 500:
206 Если же эти директивы поместить в location /download/, то нужно 231 <example>
207 заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт 232 location /download/ {
208 ошибку 500: 233 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
209 <example> 234 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
210 location /download/ { 235 return 403;
211 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; 236 }
212 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
213 return 403;
214 }
215 </example> 237 </example>
216 </para> 238 </para>
217 239
218 <para> 240 <para>
219 Если в строке замены указаны аргументы, то предыдущие аргументы запроса 241 Если в строке замены указаны аргументы, то предыдущие аргументы запроса
220 добавляются после них. Можно отказаться от этого добавления, указав 242 добавляются после них.
221 в конце строки замены знак вопроса: 243 Можно отказаться от этого добавления, указав в конце строки замены знак вопроса:
222 <example> 244 <example>
223 rewrite ^/users/(.*)$ /show?user=$1? last; 245 rewrite ^/users/(.*)$ /show?user=$1? last;
224 </example> 246 </example>
225 </para> 247 </para>
226 248
227 <para> 249 <para>
228 Если в регулярном выражении встречаются символы "}" или ";", то 250 Если в регулярном выражении встречаются символы “<literal>}</literal>”
229 всё выражение нужно заключить в одинарные или двойные кавычки. 251 или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные
252 или двойные кавычки.
230 </para> 253 </para>
231 254
232 </directive> 255 </directive>
233 256
234 257
235 <directive name="set"> 258 <directive name="set">
236 <syntax><value>переменная</value> <value>значение</value></syntax> 259 <syntax><value>переменная</value> <value>значение</value></syntax>
237 <default/> 260 <default/>
238 <context>server, location, if</context> 261 <context>server</context>
239 262 <context>location</context>
240 <para> 263 <context>if</context>
241 Директива устанавливает значение для указанной переменной. 264
265 <para>
266 Устанавливает значение для указанной переменной.
242 В качестве значения можно использовать текст, переменные и их комбинации. 267 В качестве значения можно использовать текст, переменные и их комбинации.
243 </para> 268 </para>
244 269
245 </directive> 270 </directive>
246 271
247 272
248 <directive name="uninitialized_variable_warn"> 273 <directive name="uninitialized_variable_warn">
249 <syntax><literal>on</literal> | <literal>off</literal></syntax> 274 <syntax><literal>on</literal> | <literal>off</literal></syntax>
250 <default>on</default> 275 <default>on</default>
251 <context>http, server, location, if</context> 276 <context>http</context>
252 277 <context>server</context>
253 <para> 278 <context>location</context>
254 Директива определяет, нужно ли писать в лог предупреждение 279 <context>if</context>
280
281 <para>
282 Определяет, нужно ли писать в лог предупреждение
255 о неинициализированной переменной. 283 о неинициализированной переменной.
256 </para> 284 </para>
257 285
258 </directive> 286 </directive>
259 287
260 </section> 288 </section>
261 289
262 290
263 <section name="Внутреннее устройство" id="internals"> 291 <section id="internals" name="Внутреннее устройство">
264 292
265 <para> 293 <para>
266 Директивы модуля ngx_http_rewrite_module компилируется на стадии 294 Директивы модуля <literal>ngx_http_rewrite_module</literal>
267 конфигурирования во внутренние коды, исполняемые во время запроса 295 компилируются на стадии конфигурации во внутренние коды,
268 интерпретатором. Интерпретатор представляет из себя простую 296 исполняемые во время запроса интерпретатором.
269 стековую виртуальную машину. 297 Интерпретатор представляет из себя простую стековую виртуальную машину.
270 </para> 298 </para>
271 299
272 <para> 300 <para>
273 Например, директивы 301 Например, директивы
274 <example> 302 <example>
275 location /download/ { 303 location /download/ {
276 if ($forbidden) { 304 if ($forbidden) {
277 return 403; 305 return 403;
278 }
279
280 if ($slow) {
281 limit_rate 10k;
282 }
283
284 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
285 } 306 }
307
308 if ($slow) {
309 limit_rate 10k;
310 }
311
312 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
313 }
286 </example> 314 </example>
287 будет скомпилированы в такие коды: 315 будет скомпилированы в такие коды:
288 <example> 316 <example>
289 переменная $forbidden 317 переменная $forbidden
290 проверка на ноль 318 проверка на ноль
291 возврат 403 319 возврат 403
292 завершение всего кода
293 переменная $slow
294 проверка на ноль
295 проверка регулярного выражения
296 копирование "/"
297 копирование $1
298 копирование "/mp3/"
299 копирование $2
300 копирование ".mp3"
301 завершение регулярного выражения
302 завершение всего кода 320 завершение всего кода
303 </example> 321 переменная $slow
304 </para> 322 проверка на ноль
305 323 проверка регулярного выражения
306 <para> 324 копирование "/"
307 Обратите внимание, что кода для директивы limit_rate нет, поскольку 325 копирование $1
308 она не имеет отношения к модулю ngx_http_rewrite_module. Для блока 326 копирование "/mp3/"
309 if создаётся такая же конфигурация, как и для блока location. 327 копирование $2
328 копирование ".mp3"
329 завершение регулярного выражения
330 завершение всего кода
331 </example>
332 </para>
333
334 <para>
335 Обратите внимание, что кода для директивы
336 <link doc="ngx_http_core_module.xml" id="limit_rate"/>
337 нет, поскольку она не имеет отношения к модулю
338 <literal>ngx_http_rewrite_module</literal>.
339 Для блока <link id="if"/> создаётся такая же конфигурация, как и для блока
340 <link doc="ngx_http_core_module.xml" id="location"/>.
310 Если условие истинно, то запрос получает конфигурацию, соответствующую 341 Если условие истинно, то запрос получает конфигурацию, соответствующую
311 блоку if, и в этой конфигурации limit_rate равен 10k. 342 блоку <literal>if</literal>,
343 и в этой конфигурации <literal>limit_rate</literal> равен 10k.
312 </para> 344 </para>
313 345
314 <para> 346 <para>
315 Директиву 347 Директиву
316 <example> 348 <example>
317 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; 349 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
318 </example> 350 </example>
319 можно сделать на один код меньше, если в регулярном выражении включить 351 можно сделать на один код меньше, если в регулярном выражении включить
320 первый слэш в скобки: 352 первый слэш в скобки:
321 <example> 353 <example>
322 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; 354 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
323 </example> 355 </example>
324 тогда её коды будут выглядеть так: 356 тогда её коды будут выглядеть так:
325 <example> 357 <example>
326 проверка регулярного выражения 358 проверка регулярного выражения
327 копирование $1 359 копирование $1
328 копирование "/mp3/" 360 копирование "/mp3/"
329 копирование $2 361 копирование $2
330 копирование ".mp3" 362 копирование ".mp3"
331 завершение регулярного выражения 363 завершение регулярного выражения
332 завершение всего кода 364 завершение всего кода
333 </example> 365 </example>
334 </para> 366 </para>
335 367
336 </section> 368 </section>
337 369