changeset 535:f8652d663b62

Revised description of "proxy_pass".
author Ruslan Ermilov <ru@nginx.com>
date Thu, 14 Jun 2012 13:08:13 +0000
parents 6761e05e5128
children 8068d592b390
files xml/en/docs/http/ngx_http_proxy_module.xml xml/ru/docs/http/ngx_http_proxy_module.xml
diffstat 2 files changed, 121 insertions(+), 99 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_proxy_module.xml
+++ b/xml/en/docs/http/ngx_http_proxy_module.xml
@@ -809,18 +809,20 @@ Can be used along with the <link id="pro
 <context>limit_except</context>
 
 <para>
-Sets an address of the proxied server and a URI that maps a location.
-An address can be specified as a domain name or an address, and a port,
-for example,
+Sets the protocol and address of a proxied server, and an optional URI
+to which a location should be mapped.
+A protocol can be specified as
+“<literal>http</literal>” or “<literal>https</literal>”.
+An address can be specified as a domain name or IP address,
+and an optional port:
 <example>
 proxy_pass http://localhost:8000/uri/;
 </example>
-or as a UNIX-domain socket path:
+or as a UNIX-domain socket path specified after the word
+“<literal>unix</literal>” and enclosed in colons:
 <example>
 proxy_pass http://unix:/tmp/backend.socket:/uri/;
 </example>
-here a path is specified after the word “<literal>unix</literal>”
-and enclosed in two colons.
 </para>
 
 <para>
@@ -831,70 +833,79 @@ In addition, an address can be specified
 </para>
 
 <para>
-When passing a request to the server, part of a URI matching the location
-is replaced by a URI specified in the <literal>proxy_pass</literal> directive.
-This rule has two exceptions where a replacement location cannot be
-defined:
-<list type="bullet">
+A request URI is passed to the server as follows:
+<list type="bullet" compact="no">
 
 <listitem>
-when a location is specified using a regular expression;
+If <literal>proxy_pass</literal> is specified with URI,
+when passing a request to the server, part of a
+<link doc="ngx_http_core_module.xml" id="location">normalized</link>
+request URI matching the location is replaced by a URI
+specified in the directive:
+<example>
+location /name/ {
+    proxy_pass http://127.0.0.1/remote/;
+}
+</example>
 </listitem>
 
 <listitem>
-if a URI is changed using the
-<link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive
-inside a proxied location, and this same configuration will be
-used to process a request (<literal>break</literal>):
+If <literal>proxy_pass</literal> is specified without URI,
+a request URI is passed to the server in the same form
+as sent by a client when processing an original request,
+or the full normalized request URI is passed
+when processing the changed URI:
+<example>
+location /some/path/ {
+    proxy_pass http://127.0.0.1;
+}
+</example>
+<note>
+Before version 1.1.12,
+if <literal>proxy_pass</literal> is specified without a URI,
+an original request URI might be passed
+instead of the changed URI in some cases.
+</note>
+</listitem>
+</list>
+</para>
+
+<para>
+In some cases, part of a request URI to be replaced cannot be determined:
+<list type="bullet" compact="no">
+
+<listitem>
+When location is specified using a regular expression.
+<para>
+In this case, the directive should be specified without URI.
+</para>
+</listitem>
+
+<listitem>
+When URI is changed inside a proxied location using the
+<link doc="ngx_http_rewrite_module.xml" id="rewrite"/> directive,
+and this same configuration will be used to process a request
+(<literal>break</literal>):
 <example>
 location /name/ {
     rewrite    /name/([^/]+) /users?name=$1 break;
     proxy_pass http://127.0.0.1;
 }
 </example>
-In these cases a URI is passed without mapping.
+<para>
+In this case, a URI specified in the directive is ignored and
+the full changed request URI is passed to the server.
+</para>
 </listitem>
-
 </list>
 </para>
 
 <para>
-It can also be specified that a request URI should be passed unchanged,
-in the same form it was sent by the client, not the processed form.
-During a processing
-<list type="bullet">
-
-<listitem>
-two or more adjacent slashes are replaced by one: “//” — “/”;
-</listitem>
-
-<listitem>
-links to the current directory get removed: “/./” — “/”;
-</listitem>
-
-<listitem>
-links to the parent directory get removed: “/dir/../” — “/”.
-</listitem>
-
-</list>
-</para>
-
-<para>
-If a URI should be passed unchanged then the server URL should be specified
-without a URI in the <literal>proxy_pass</literal> directive:
-<example>
-location /some/path/ {
-    proxy_pass http://127.0.0.1;
-}
-</example>
-</para>
-
-<para>
-Server name, its port, and passed URI can be specified using variables:
+A server name, its port and passed URI can also be specified using variables:
 <example>
 proxy_pass http://$host$uri;
 </example>
-or like this:
+or even like this:
 <example>
 proxy_pass $request;
 </example>
--- a/xml/ru/docs/http/ngx_http_proxy_module.xml
+++ b/xml/ru/docs/http/ngx_http_proxy_module.xml
@@ -805,40 +805,80 @@ proxy_no_cache $http_pragma    $http_aut
 <context>limit_except</context>
 
 <para>
-Задаёт адрес проксируемоего сервера и URI, на который
-будет отображаться location.
-Адрес может быть указан в виде доменного имени или адреса, и порта, например,
+Задаёт протокол и адрес проксируемоего сервера, а также необязательный URI,
+на который должен отображаться location.
+В качестве протокола можно указать
+“<literal>http</literal>” или “<literal>https</literal>”.
+Адрес может быть указан в виде доменного имени или IP-адреса,
+и необязательного порта:
 <example>
 proxy_pass http://localhost:8000/uri/;
 </example>
-или в виде пути UNIX-сокета:
+или в виде пути UNIX-сокета, который указывается после слова
+“<literal>unix</literal>” и заключается в двоеточия:
 <example>
 proxy_pass http://unix:/tmp/backend.socket:/uri/;
 </example>
-путь указан после слова “<literal>unix</literal>”
-и заключён между двумя двоеточиями.
 </para>
 
 <para>
 Если доменному имени соответствует несколько адресов, то все они будут
 использоваться по очереди (round-robin).
-И, кроме того, адрес может быть
-<link doc="ngx_http_upstream_module.xml">группой серверов</link>.
+Кроме того, в качестве адреса можно указать
+<link doc="ngx_http_upstream_module.xml">группу серверов</link>.
 </para>
 
 <para>
-При передаче запроса серверу часть URI, соответствующая location,
-заменяется на URI, указанный в директиве <literal>proxy_pass</literal>.
-Но из этого правила есть два исключения, в которых нельзя определить
-заменяемый location:
-<list type="bullet">
+URI запроса передаётся на сервер так:
+<list type="bullet" compact="no">
 
 <listitem>
-если location задан регулярным выражением;
+Если <literal>proxy_pass</literal> указана с URI,
+то при передаче запроса серверу часть
+<link doc="ngx_http_core_module.xml" id="location">нормализованного</link>
+URI запроса, соответствующая location, заменяется на URI,
+указанный в директиве:
+<example>
+location /name/ {
+    proxy_pass http://127.0.0.1/remote/;
+}  
+</example>
 </listitem>
 
 <listitem>
-если внутри проксируемого location с помощью директивы
+Если <literal>proxy_pass</literal> указана без URI,
+то при обработке первоначального запроса на сервер передаётся
+URI запроса в том же виде, в каком его прислал клиент,
+а при обработке изменённого URI&mdash;
+нормализованный URI запроса целиком:
+<example>
+location /some/path/ {
+    proxy_pass http://127.0.0.1;
+}
+</example>
+<note>
+До версии 1.1.12,
+если <literal>proxy_pass</literal> указана без URI,
+в ряде случаев при изменении URI на сервер мог передаваться
+URI первоначального запроса вместо изменённого URI.
+</note>
+</listitem>
+</list>
+</para>
+
+<para>
+В ряде случаев часть URI запроса, подлежащую замене, выделить невозможно:
+<list type="bullet" compact="no">
+
+<listitem>
+Если location задан регулярным выражением.
+<para>
+В этом случае директиву следует указывать без URI.
+</para>
+</listitem>
+
+<listitem>
+Если внутри проксируемого location с помощью директивы
 <link doc="ngx_http_rewrite_module.xml" id="rewrite"/> изменяется
 URI, и именно с этой конфигурацией будет обрабатываться запрос
 (<literal>break</literal>):
@@ -848,50 +888,21 @@ location /name/ {
     proxy_pass http://127.0.0.1;
 }
 </example>
-Для этих случаев URI передаётся без отображения.
-</listitem>
-
-</list>
+<para>
+В этом случае URI, указанный в директиве, игнорируется, и на сервер
+передаётся изменённый URI запроса целиком.
 </para>
-
-<para>
-Кроме того, можно указать, чтобы URI запроса передавался в том же виде,
-в каком его прислал клиент, а не в обработанном виде.
-Во время обработки
-<list type="bullet">
-
-<listitem>
-два и более слэшей заменяются на один: “//” — “/”;
 </listitem>
-
-<listitem>
-убираются ссылки на текущий каталог: “/./” — “/”;
-</listitem>
-
-<listitem>
-убираются ссылки на предыдущий каталог: “/dir/../” — “/”.
-</listitem>
-
 </list>
 </para>
 
 <para>
-Если на сервер нужно передать URI в необработанном виде, то для этого
-в директиве <literal>proxy_pass</literal> нужно указать URL сервера без URI:
-<example>
-location /some/path/ {
-    proxy_pass http://127.0.0.1;
-}
-</example>
-</para>
-
-<para>
 Имя сервера, его порт и передаваемый URI можно также полностью задать
 с помощью переменных:
 <example>
 proxy_pass http://$host$uri;
 </example>
-или так:
+или даже так:
 <example>
 proxy_pass $request;
 </example>