Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_rewrite_module.xml @ 76:4a4caa566120

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Russian documentation import. Changes in module.dtd: <example> now allowed to contain <value> and <emphasis> elements (we need this to show important parts in examples), less strict checking of <directive> syntax (we don't want to fully document some directives, notably deprecated ones). Known issues: 1. <syntax> elements are preserved as is, they will require manual conversion (likely to some not-yet-existed format a la DocBook cmdsynopsis, as currently used one seems to be incomplete); 2. <value> no longer corresponds to replaceable content, and it's use in examples isn't correct; 3. <link doc="document#fragment"> doesn't work with current xslt, either should be supported or changed to <link doc="document" id="fragment">. The following files are intentionally omitted: maillists.xml (support.xml should be used instead), experimental.xml (obsolete), faq.xml (conflicts with existing one, needs discussion). Not yet linked to site.
author Maxim Dounin <mdounin@mdounin.ru>
date Tue, 11 Oct 2011 12:57:50 +0000
parents
children 0a45870d0160
comparison
equal deleted inserted replaced
75:2bf4cd2787c5 76:4a4caa566120
1 <?xml version="1.0" encoding="utf-8"?>
2
3 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
4
5 <module name="Директивы модуля ngx_http_rewrite_module"
6 link="/ru/docs/http/ngx_http_rewrite_module.html"
7 lang="ru">
8
9 <section name="" id="summary">
10
11 <para>
12 Модуль ngx_http_rewrite_module позволяет изменять URI с помощью
13 регулярных выражений, делать редиректы и выбирать конфигурацию
14 в зависимости от переменных. Если директивы этого модуля описаны
15 на уровне сервера, то они выполняются до того, как определяется
16 location для запроса. Если в выбранном location тоже есть
17 директивы модуля ngx_http_rewrite_module, то они также выполняются.
18 Если URI изменился в результате исполнения директив внутри location,
19 то снова определяется location для уже нового URI. Этот цикл может
20 повторяться до 10 раз, после чего nginx возвращает ошибку
21 "Server Internal Error" (500).
22 </para>
23
24 </section>
25
26
27 <section name="Директивы" id="directives">
28
29 <directive name="break">
30 <syntax>break</syntax>
31 <default>нет</default>
32 <context>server, location, if</context>
33
34 <para>
35 Директива завершает обработку текущего набора директив
36 ngx_http_rewrite_module.
37 </para>
38
39 <para>
40 Пример использования:
41 <example>
42 if ($slow) {
43 limit_rate 10k;
44 break;
45 }
46 </example>
47 </para>
48
49 </directive>
50
51
52 <directive name="if">
53 <syntax>if (<value>условие</value>) { ... }</syntax>
54 <default>нет</default>
55 <context>server, location</context>
56
57 <para>
58 Директива if проверяет истинность условия, если оно истинно,
59 то выполняется указанный в фигурных скобках код и запрос обрабатывается
60 в соответствии с заданной там же конфигурацией.
61 Конфигурация внутри директивы if наследуется из предыдущего уровня.
62 </para>
63
64 <para>
65 В качестве условия могут быть заданы:
66 <list type="bullet">
67
68 <listitem>
69 имя переменной; ложными значениями переменной являются пустая строка ""
70 или любая строка, начинающиеся на "0";
71 </listitem>
72
73 <listitem>
74 сравнение переменной со строкой с помощью операторов "=" и "!=";
75 </listitem>
76
77 <listitem>
78 проверка переменной с помощью регулярного выражения без учёта
79 регистра символов — "~*" и с учётом — "~".
80 В регулярных выражениях можно использовать выделения, которые затем
81 доступны в виде переменных $1 — $9.
82 Также можно использовать отрицательные операторы "!~" и "!~*".
83 Если в регулярном выражении встречаются символы "}" или ";", то
84 всё выражение нужно заключить в одинарные или двойные кавычки.
85 </listitem>
86
87 <listitem>
88 проверка существования файла с помощью операторов "-f" и "!-f";
89 </listitem>
90
91 <listitem>
92 проверка существования каталога с помощью операторов "-d" и "!-d";
93 </listitem>
94
95 <listitem>
96 проверка существования файла, каталога или символической ссылки
97 с помощью операторов "-e" и "!-e";
98 </listitem>
99
100 <listitem>
101 проверка исполняемости файла с помощью операторов "-x" и "!-x".
102 </listitem>
103
104 </list>
105 </para>
106
107 <para>
108 Примеры использования:
109 <example>
110 if ($http_user_agent ~ MSIE) {
111 rewrite ^(.*)$ /msie/$1 break;
112 }
113
114 if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) {
115 set $id $1;
116 }
117
118 if ($request_method = POST ) {
119 return 405;
120 }
121
122
123 if ($slow) {
124 limit_rate 10k;
125 }
126
127 if ($invalid_referer) {
128 return 403;
129 }
130 </example>
131 Значение встроенной переменной $invalid_referer задаётся директивой <link doc="ngx_http_referer_module.xml#valid_referers">valid_referers</link>.
132 </para>
133
134 </directive>
135
136
137 <directive name="return">
138 <syntax>return <value>код</value></syntax>
139 <default>нет</default>
140 <context>server, location, if</context>
141
142 <para>
143 Директива return завершает исполнение кода и возвращает клиенту
144 указанный код. Можно использовать следующие значения: 204, 400,
145 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
146 Кроме того, нестандартный код 444 закрывает соединение без передачи
147 заголовка ответа.
148 </para>
149
150 </directive>
151
152
153 <directive name="rewrite">
154 <syntax>rewrite <value>regex</value> <value>замена</value>
155  <value>флаг</value>
156 </syntax>
157 <default>нет</default>
158 <context>server, location, if</context>
159
160 <para>
161 Директива rewrite изменяет URI в соответствии с регулярным выражением
162 и строкой замены. Директивы выполняются в порядке их следования в
163 конфигурационном файле. С помощью флагов можно досрочно прекратить
164 исполнение директив. Если строка замены начинается с "http://", то
165 клиенту будет возвращён редирект и обработка директив также завершается.
166 </para>
167
168 <para>
169 Флаги могут быть следующими:
170 <list type="bullet">
171
172 <listitem>
173 last — завершает обработку текущего набора директив
174 ngx_http_rewrite_module, после чего ищется соответствие URI и location;
175 </listitem>
176
177 <listitem>
178 break — завершает обработку текущего набора директив
179 ngx_http_rewrite_module;
180 </listitem>
181
182 <listitem>
183 redirect — возвращает временный редирект с кодом 302;
184 используется, если заменяющая строка не начинается с "http://";
185 </listitem>
186
187 <listitem>
188 permanent — возвращает постоянный редирект с кодом 301.
189 </listitem>
190
191 </list>
192 </para>
193
194 <para>
195 </para>
196
197 <para>
198 Пример использования:
199 <example>
200 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
201 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last;
202 return 403;
203 </example>
204 </para>
205
206 <para>
207 Если же эти директивы поместить в location /download/, то нужно
208 заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт
209 ошибку 500:
210 <example>
211 location /download/ {
212 rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
213 rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break;
214 return 403;
215 }
216 </example>
217 </para>
218
219 <para>
220 Если в строке замены указаны аргументы, то предыдущие аргументы запроса
221 добавляются после них. Можно отказаться от этого добавления, указав
222 в конце строки замены знак вопроса:
223 <example>
224 rewrite ^/users/(.*)$ /show?user=$1? last;
225 </example>
226 </para>
227
228 <para>
229 Если в регулярном выражении встречаются символы "}" или ";", то
230 всё выражение нужно заключить в одинарные или двойные кавычки.
231 </para>
232
233 </directive>
234
235
236 <directive name="set">
237 <syntax>set <value>переменная</value> <value>значение</value>
238 </syntax>
239 <default>нет</default>
240 <context>server, location, if</context>
241
242 <para>
243 Директива устанавливает значение для указанной переменной.
244 В качестве значения можно использовать текст, переменные и их комбинации.
245 </para>
246
247 </directive>
248
249
250 <directive name="uninitialized_variable_warn">
251 <syntax>uninitialized_variable_warn <value>on|off</value></syntax>
252 <default>uninitialized_variable_warn on</default>
253 <context>http, server, location, if</context>
254
255 <para>
256 Директива определяет, нужно ли писать в лог предупреждение
257 о неинициализированной переменной.
258 </para>
259
260 </directive>
261
262 </section>
263
264
265 <section name="Внутреннее устройство" id="internals">
266
267 <para>
268 Директивы модуля ngx_http_rewrite_module компилируется на стадии
269 конфигурирования во внутренние коды, исполняемые во время запроса
270 интерпретатором. Интерпретатор представляет из себя простую
271 стековую виртуальную машину.
272 </para>
273
274 <para>
275 Например, директивы
276 <example>
277 location /download/ {
278 if ($forbidden) {
279 return 403;
280 }
281
282 if ($slow) {
283 limit_rate 10k;
284 }
285
286 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
287 }
288 </example>
289 будет скомпилированы в такие коды:
290 <example>
291 переменная $forbidden
292 проверка на ноль
293 возврат 403
294 завершение всего кода
295 переменная $slow
296 проверка на ноль
297 проверка регулярного выражения
298 копирование "/"
299 копирование $1
300 копирование "/mp3/"
301 копирование $2
302 копирование ".mp3"
303 завершение регулярного выражения
304 завершение всего кода
305 </example>
306 </para>
307
308 <para>
309 Обратите внимание, что кода для директивы limit_rate нет, поскольку
310 она не имеет отношения к модулю ngx_http_rewrite_module. Для блока
311 if создаётся такая же конфигурация, как и для блока location.
312 Если условие истинно, то запрос получает конфигурацию, соответствующую
313 блоку if, и в этой конфигурации limit_rate равен 10k.
314 </para>
315
316 <para>
317 Директиву
318 <example>
319 rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
320 </example>
321 можно сделать на один код меньше, если в регулярном выражении включить
322 первый слэш в скобки:
323 <example>
324 rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
325 </example>
326 тогда её коды будут выглядеть так:
327 <example>
328 проверка регулярного выражения
329 копирование $1
330 копирование "/mp3/"
331 копирование $2
332 копирование ".mp3"
333 завершение регулярного выражения
334 завершение всего кода
335 </example>
336 </para>
337
338 </section>
339
340 </module>