Mercurial > hg > nginx-site
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— +нормализованный 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>