Mercurial > hg > nginx-site

changeset 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 8ad9df891e23
children a73fa21add8a
files xml/ru/docs/http/ngx_http_rewrite_module.xml
diffstat 1 files changed, 175 insertions(+), 143 deletions(-) [+]
line wrap: on
line diff
--- a/xml/ru/docs/http/ngx_http_rewrite_module.xml	Mon Jan 30 19:34:03 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_rewrite_module.xml	Tue Jan 31 16:29:31 2012 +0000
@@ -2,47 +2,50 @@
 
 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
 
-<module name="Директивы модуля ngx_http_rewrite_module"
+<module name="Модуль ngx_http_rewrite_module"
         link="/ru/docs/http/ngx_http_rewrite_module.html"
         lang="ru">
 
 <section id="summary">
 
 <para>
-Модуль ngx_http_rewrite_module позволяет изменять URI с помощью
-регулярных выражений, делать перенаправления и выбирать конфигурацию
-в зависимости от переменных. Если директивы этого модуля описаны
-на уровне сервера, то они выполняются до того, как определяется
-location для запроса. Если в выбранном location тоже есть
-директивы модуля ngx_http_rewrite_module, то они также выполняются.
+Модуль <literal>ngx_http_rewrite_module</literal> позволяет
+изменять URI с помощью регулярных выражений, делать перенаправления
+и выбирать конфигурацию в зависимости от переменных.
+Если директивы этого модуля описаны на уровне сервера, то они
+выполняются до того, как определяется location для запроса.
+Если в выбранном location тоже есть директивы модуля
+<literal>ngx_http_rewrite_module</literal>, то они также выполняются.
 Если URI изменился в результате исполнения директив внутри location,
-то снова определяется location для уже нового URI. Этот цикл может
-повторяться до 10 раз, после чего nginx возвращает ошибку
-"Server Internal Error" (500).
+то снова определяется location для уже нового URI.
+Этот цикл может повторяться до 10 раз, после чего nginx возвращает
+ошибку <http-status code="500" text="Internal Server Error"/>.
 </para>
 
 </section>
 
 
-<section name="Директивы" id="directives">
+<section id="directives" name="Директивы">
 
 <directive name="break">
 <syntax/>
 <default/>
-<context>server, location, if</context>
+<context>server</context>
+<context>location</context>
+<context>if</context>
 
 <para>
-Директива завершает обработку текущего набора директив
-ngx_http_rewrite_module.
+Завершает обработку текущего набора директив модуля
+<literal>ngx_http_rewrite_module</literal>.
 </para>
 
 <para>
-Пример использования:
+Пример:
 <example>
-    if ($slow) {
-        limit_rate  10k;
-        break;
-    }
+if ($slow) {
+    limit_rate 10k;
+    break;
+}
 </example>
 </para>
 
@@ -52,13 +55,16 @@
 <directive name="if">
 <syntax block="yes">(<value>условие</value>)</syntax>
 <default/>
-<context>server, location</context>
+<context>server</context>
+<context>location</context>
 
 <para>
-Директива if проверяет истинность условия, если оно истинно,
+Проверяет истинность условия.
+Если оно истинно,
 то выполняется указанный в фигурных скобках код и запрос обрабатывается
 в соответствии с заданной там же конфигурацией.
-Конфигурация внутри директивы if наследуется из предыдущего уровня.
+Конфигурация внутри директивы <literal>if</literal> наследуется с
+предыдущего уровня.
 </para>
 
 <para>
@@ -66,69 +72,75 @@
 <list type="bullet">
 
 <listitem>
-имя переменной; ложными значениями переменной являются пустая строка ""
-или любая строка, начинающиеся на "0";
+имя переменной; ложными значениями переменной являются пустая строка “”
+или любая строка, начинающаяся на “<literal>0</literal>”;
 </listitem>
 
 <listitem>
-сравнение переменной со строкой с помощью операторов "=" и "!=";
+сравнение переменной со строкой с помощью операторов
+“<literal>=</literal>” и “<literal>!=</literal>”;
 </listitem>
 
 <listitem>
-проверка переменной с помощью регулярного выражения без учёта
-регистра символов — "~*" и с учётом — "~".
+проверка переменной с помощью регулярного выражения с учётом
+регистра символов — “<literal>~</literal>” и без него — “<literal>~*</literal>”.
 В регулярных выражениях можно использовать выделения, которые затем
-доступны в виде переменных $1 — $9.
-Также можно использовать отрицательные операторы "!~" и "!~*".
-Если в регулярном выражении встречаются символы "}" или ";", то
-всё выражение нужно заключить в одинарные или двойные кавычки.
+доступны в виде переменных <var>$1</var> — <var>$9</var>.
+Также можно использовать отрицательные операторы “<literal>!~</literal>”
+и “<literal>!~*</literal>”.
+Если в регулярном выражении встречаются символы “<literal>}</literal>”
+или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные
+или двойные кавычки.
 </listitem>
 
 <listitem>
-проверка существования файла с помощью операторов "-f" и "!-f";
+проверка существования файла с помощью операторов “<literal>-f</literal>”
+и “<literal>!-f</literal>”;
 </listitem>
 
 <listitem>
-проверка существования каталога с помощью операторов "-d" и "!-d";
+проверка существования каталога с помощью операторов “<literal>-d</literal>”
+и “<literal>!-d</literal>”;
 </listitem>
 
 <listitem>
 проверка существования файла, каталога или символической ссылки
-с помощью операторов "-e" и "!-e";
+с помощью операторов “<literal>-e</literal>” и “<literal>!-e</literal>”;
 </listitem>
 
 <listitem>
-проверка исполняемости файла с помощью операторов "-x" и "!-x".
+проверка исполняемости файла с помощью операторов “<literal>-x</literal>”
+и “<literal>!-x</literal>”.
 </listitem>
 
 </list>
 </para>
 
 <para>
-Примеры использования:
+Примеры:
 <example>
-    if ($http_user_agent ~ MSIE) {
-        rewrite  ^(.*)$  /msie/$1  break;
-    }
+if ($http_user_agent ~ MSIE) {
+    rewrite ^(.*)$ /msie/$1 break;
+}
 
-    if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) {
-        set  $id  $1;
-    }
+if ($http_cookie ~* "id=([^;]+)(?:;|$)") {
+    set $id $1;
+}
 
-    if ($request_method = POST ) {
-        return 405;
-    }
+if ($request_method = POST) {
+    return 405;
+}
 
 
-    if ($slow) {
-        limit_rate  10k;
-    }
+if ($slow) {
+    limit_rate 10k;
+}
 
-    if ($invalid_referer) {
-        return   403;
-    }
+if ($invalid_referer) {
+    return 403;
+}
 </example>
-Значение встроенной переменной $invalid_referer задаётся директивой
+Значение встроенной переменной <var>$invalid_referer</var> задаётся директивой
 <link doc="ngx_http_referer_module.xml" id="valid_referers"/>.
 </para>
 
@@ -138,11 +150,13 @@
 <directive name="return">
 <syntax><value>код</value></syntax>
 <default/>
-<context>server, location, if</context>
+<context>server</context>
+<context>location</context>
+<context>if</context>
 
 <para>
-Директива return завершает исполнение кода и возвращает клиенту
-указанный код. Можно использовать следующие значения: 204, 400,
+Завершает исполнение кода и возвращает клиенту указанный код.
+Можно использовать следующие значения: 204, 400,
 402 — 406, 408, 410, 411, 413, 416 и 500 — 504.
 Кроме того, нестандартный код 444 закрывает соединение без передачи
 заголовка ответа.
@@ -152,93 +166,104 @@
 
 
 <directive name="rewrite">
-<syntax><value>regex</value> <value>замена</value> <value>флаг</value></syntax>
+<syntax>
+    <value>regex</value>
+    <value>замена</value>
+    [<value>флаг</value>]</syntax>
 <default/>
-<context>server, location, if</context>
+<context>server</context>
+<context>location</context>
+<context>if</context>
 
 <para>
-Директива rewrite изменяет URI в соответствии с регулярным выражением
-и строкой замены. Директивы выполняются в порядке их следования в
-конфигурационном файле. С помощью флагов можно досрочно прекратить
-исполнение директив. Если строка замены начинается с "http://", то
-клиенту будет возвращено перенаправление и обработка директив также завершается.
+Изменяет URI в соответствии с регулярным выражением и строкой замены.
+Директивы выполняются в порядке их следования в конфигурационном файле.
+С помощью флагов можно досрочно прекратить исполнение директив.
+Если строка замены начинается с “<literal>http://</literal>”, то клиенту
+будет возвращено перенаправление и обработка директив также завершается.
 </para>
 
 <para>
 Флаги могут быть следующими:
-<list type="bullet">
+<list type="tag">
 
-<listitem>
-last — завершает обработку текущего набора директив
-ngx_http_rewrite_module, после чего ищется соответствие URI и location;
-</listitem>
+<tag-name><literal>last</literal></tag-name>
+<tag-desc>
+завершает обработку текущего набора директив модуля
+<literal>ngx_http_rewrite_module</literal>,
+после чего ищется соответствие URI и location;
+</tag-desc>
 
-<listitem>
-break — завершает обработку текущего набора директив
-ngx_http_rewrite_module;
-</listitem>
+<tag-name><literal>break</literal></tag-name>
+<tag-desc>
+завершает обработку текущего набора директив модуля
+<literal>ngx_http_rewrite_module</literal>;
+</tag-desc>
 
-<listitem>
-redirect — возвращает временное перенаправление с кодом 302;
-используется, если заменяющая строка не начинается с "http://";
-</listitem>
+<tag-name><literal>redirect</literal></tag-name>
+<tag-desc>
+возвращает временное перенаправление с кодом 302;
+используется, если заменяющая строка не начинается с
+“<literal>http://</literal>”;
+</tag-desc>
 
-<listitem>
-permanent — возвращает постоянное перенаправление с кодом 301.
-</listitem>
+<tag-name><literal>permanent</literal></tag-name>
+<tag-desc>
+возвращает постоянное перенаправление с кодом 301.
+</tag-desc>
 
 </list>
 </para>
 
 <para>
-</para>
-
-<para>
-Пример использования:
+Пример:
 <example>
-    rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  last;
-    rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   last;
-    return   403;
+rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last;
+rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  last;
+return  403;
 </example>
 </para>
 
 <para>
-Если же эти директивы поместить в location /download/, то нужно
-заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт
-ошибку 500:
+Если же эти директивы поместить в location “<literal>/download/</literal>”,
+то нужно заменить флаг <literal>last</literal> на <literal>break</literal>,
+иначе nginx сделает 10 циклов и вернёт ошибку 500:
 <example>
-    location /download/ {
-        rewrite  ^(/download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;
-        rewrite  ^(/download/.*)/audio/(.*)\..*$  $1/mp3/$2.ra   break;
-        return   403;
-    }
+location /download/ {
+    rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
+    rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra  break;
+    return  403;
+}
 </example>
 </para>
 
 <para>
 Если в строке замены указаны аргументы, то предыдущие аргументы запроса
-добавляются после них. Можно отказаться от этого добавления, указав
-в конце строки замены знак вопроса:
+добавляются после них.
+Можно отказаться от этого добавления, указав в конце строки замены знак вопроса:
 <example>
-    rewrite  ^/users/(.*)$  /show?user=$1?  last;
+rewrite ^/users/(.*)$ /show?user=$1? last;
 </example>
 </para>
 
 <para>
-Если в регулярном выражении встречаются символы "}" или ";", то
-всё выражение нужно заключить в одинарные или двойные кавычки.
+Если в регулярном выражении встречаются символы “<literal>}</literal>”
+или “<literal>;</literal>”, то всё выражение нужно заключить в одинарные
+или двойные кавычки.
 </para>
 
 </directive>
 
 
 <directive name="set">
-<syntax><value>переменная</value> <value>значение</value></syntax>
+<syntax><value>переменная</value> <value>значение</value></syntax>
 <default/>
-<context>server, location, if</context>
+<context>server</context>
+<context>location</context>
+<context>if</context>
 
 <para>
-Директива устанавливает значение для указанной переменной.
+Устанавливает значение для указанной переменной.
 В качестве значения можно использовать текст, переменные и их комбинации.
 </para>
 
@@ -248,10 +273,13 @@
 <directive name="uninitialized_variable_warn">
 <syntax><literal>on</literal> | <literal>off</literal></syntax>
 <default>on</default>
-<context>http, server, location, if</context>
+<context>http</context>
+<context>server</context>
+<context>location</context>
+<context>if</context>
 
 <para>
-Директива определяет, нужно ли писать в лог предупреждение
+Определяет, нужно ли писать в лог предупреждение
 о неинициализированной переменной.
 </para>
 
@@ -260,76 +288,80 @@
 </section>
 
 
-<section name="Внутреннее устройство" id="internals">
+<section id="internals" name="Внутреннее устройство">
 
 <para>
-Директивы модуля ngx_http_rewrite_module компилируется на стадии
-конфигурирования во внутренние коды, исполняемые во время запроса
-интерпретатором. Интерпретатор представляет из себя простую
-стековую виртуальную машину.
+Директивы модуля <literal>ngx_http_rewrite_module</literal>
+компилируются на стадии конфигурации во внутренние коды,
+исполняемые во время запроса интерпретатором.
+Интерпретатор представляет из себя простую стековую виртуальную машину.
 </para>
 
 <para>
 Например, директивы
 <example>
-    location /download/ {
-        if ($forbidden) {
-            return   403;
-        }
+location /download/ {
+    if ($forbidden) {
+        return 403;
+    }
 
-        if ($slow) {
-            limit_rate  10k;
-        }
+    if ($slow) {
+        limit_rate 10k;
+    }
 
-        rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;
-    }
+    rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
+}
 </example>
 будет скомпилированы в такие коды:
 <example>
-    переменная  $forbidden
-    проверка на ноль
-        возврат  403
-        завершение всего кода
-    переменная  $slow
-    проверка на ноль
-    проверка регулярного выражения
-    копирование  "/"
-    копирование  $1
-    копирование  "/mp3/"
-    копирование  $2
-    копирование  ".mp3"
-    завершение регулярного выражения
+переменная $forbidden
+проверка на ноль
+    возврат 403
     завершение всего кода
+переменная $slow
+проверка на ноль
+проверка регулярного выражения
+копирование "/"
+копирование $1
+копирование "/mp3/"
+копирование $2
+копирование ".mp3"
+завершение регулярного выражения
+завершение всего кода
 </example>
 </para>
 
 <para>
-Обратите внимание, что кода для директивы limit_rate нет, поскольку
-она не имеет отношения к модулю ngx_http_rewrite_module. Для блока
-if создаётся такая же конфигурация, как и для блока location.
+Обратите внимание, что кода для директивы
+<link doc="ngx_http_core_module.xml" id="limit_rate"/>
+нет, поскольку она не имеет отношения к модулю
+<literal>ngx_http_rewrite_module</literal>.
+Для блока <link id="if"/> создаётся такая же конфигурация, как и для блока
+<link doc="ngx_http_core_module.xml" id="location"/>.
 Если условие истинно, то запрос получает конфигурацию, соответствующую
-блоку if, и в этой конфигурации limit_rate равен 10k.
+блоку <literal>if</literal>,
+и в этой конфигурации <literal>limit_rate</literal> равен 10k.
 </para>
 
 <para>
 Директиву
 <example>
-    rewrite  ^/(download/.*)/media/(.*)\..*$  /$1/mp3/$2.mp3  break;
+rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break;
 </example>
 можно сделать на один код меньше, если в регулярном выражении включить
 первый слэш в скобки:
 <example>
-    rewrite  ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$  $1/mp3/$2.mp3  break;
+rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break;
 </example>
 тогда её коды будут выглядеть так:
 <example>
-    проверка регулярного выражения
-    копирование  $1
-    копирование  "/mp3/"
-    копирование  $2
-    копирование  ".mp3"
-    завершение регулярного выражения
-    завершение всего кода
+проверка регулярного выражения
+копирование $1
+копирование "/mp3/"
+копирование $2
+копирование ".mp3"
+завершение регулярного выражения
+завершение всего кода
 </example>
 </para>