RuHttpProxyModule

= ngx_http_proxy_module =

Модуль ngx_http_proxy_module позволяет передавать запросы другому серверу. Содержание Пример конфигурации

Директивы

 * [#proxy_buffer_size proxy_buffer_size]
 * [#proxy_buffering proxy_buffering]
 * [#proxy_buffers proxy_buffers]
 * [#proxy_hide_header proxy_hide_header]
 * [#proxy_intercept_errors proxy_intercept_errors]
 * [#proxy_pass proxy_pass]
 * [#proxy_pass_header proxy_pass_header]
 * [#proxy_redirect proxy_redirect]
 * [#proxy_read_timeout proxy_read_timeout]
 * [#proxy_redirect_errors proxy_redirect_errors]
 * [#proxy_set_header proxy_set_header]

Встроенные переменные Пример конфигурации
 * location / {
 * proxy_pass       http://localhost:8000/;
 * proxy_set_header X-Real-IP  $remote_addr;
 * }

proxy_buffer_size
syntax: proxy_buffer_size размер

default: proxy_buffer_size 4k/8k

context: http, server, location

Директива задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве proxy_buffers, однако его можно сделать меньше.

proxy_buffering
syntax: proxy_buffering on|off

default: proxy_buffering on

context: http, server, location

Директива разрешает использовать буферизацию ответа проксируемого сервера. Если буферизация включена, то nginx принимает ответ проксируемого сервера как можно быстрее, сохраняя его в буфера, заданные директивами proxy_buffer_size и proxy_buffers. Если ответ не помещается полностью в память, то его часть записывается на диск.

Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же по мере его поступления. nginx не пытается считать весь ответ проксируемого сервера, максимальный размер данных, который nginx может принять от сервера задаётся директивой proxy_buffer_size.

proxy_buffers
syntax: proxy_buffers число размер

default: proxy_buffers 8 4k/8k

context: http, server, location

Директива задаёт число и размер буферов, в которые будет читаться ответ, получаемый от проксируемого сервера. По умолчанию размер одного буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K.

proxy_hide_header
syntax: proxy_hide_header имя

context: http, server, location

nginx не передаёт клиенту строки заголовка "Date", "Server", "X-Pad" и "X-Accel-..." из ответа проксированного сервера. Директива proxy_hide_header задаёт дополнительные строки. Если же строки нужно наоброт разрешить, то нужно воспользоваться директивой proxy_pass_header.

proxy_intercept_errors
syntax: proxy_intercept_errors [on|off] 

default: proxy_intercept_errors off

context: http, server, location

Директива определяет, передавать ли клиенту проксированные ответы с кодом больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью директивы error_page.

proxy_pass
syntax: proxy_pass URL

default: нет

context: location, if в location

Директива задаёт порт или сокет, на котором слушает проксируемый сервер, и URI, на который будет отображаться location. Порт может быть указан в виде имени хоста или адреса и порта, например,
 * proxy_pass  http://localhost:8000/uri/;

а сокет — в виде пути unix сокета:
 * proxy_pass  http://unix:/tmp/backend.socket:/uri/;

путь указан после слова unix и заключён между двумя двоеточиями.

При передаче запроса серверу часть URI, соответствующая location, заменяется на URI, указанный в директиве proxy_pass. Но из этого правила есть два исключения, в которых нельзя определить заменяемый location:


 * если location задан регулярным выражением;
 * если внутри проксируемого location с помощью директивы rewrite изменяется URI и именно с этой конфигурацией будет обрабатываться запрос (break):
 * location /name/ {
 * rewrite     /name/([^/] +)  /users?name=$1  break;
 * proxy_pass  http://127.0.0.1;
 * }


 * Для этих случаев URI передаётся без отображения.

Кроме того, можно указать, чтобы URI запроса передавалось в том же виде, как его прислал клиент, а не в в обработанном виде. Во время обработки


 * два и более слэшей преобразуются в один слэш: "//" — "/";
 * убираются ссылки на текущий каталог: "/./" — "/";
 * убираются ссылки на предыдущий каталог: "/dir/../" — "/".

Если на сервер нужно передать URI в необработанном виде, то для этого в директиве proxy_pass нужно указать URL сервера без URI:
 * location /some/path/ {
 * proxy_pass  http://127.0.0.1;
 * }

proxy_pass_header
syntax: proxy_pass_header имя

context: http, server, location

Директива разрешает передавать клиенту запрещённые для передачи строки.

proxy_redirect
syntax: proxy_redirect [default|off|редирект замена] 

default: proxy_redirect default

context: http, server, location

Директива задаёт текст, который нужно изменить в строках заголовка "Location" и "Refresh" в ответе проксируемого сервера. Предположим, проксируемый сервер вернул строку "Location: http://localhost:8000/two/some/uri/". Директива
 * proxy_redirect  http://localhost:8000/two/   http://frontend/one/;

перепишет эту строку в виде "Location: http://frontend/one/some/uri/".

В заменяемой строке можно не указывать имя сервера:
 * proxy_redirect  http://localhost:8000/two/   /;

тогда будет поставлено основное имя сервера и порт, если он отличен от 80.

Изменение по умолчанию, задаваемое параметром "default", использует параметры директив location и proxy_pass. Поэтому две нижеприведённые конфигурации одинаковы:
 * location /one/ {
 * proxy_pass      http://upstream:port/two/;
 * proxy_redirect  default;


 * location /one/ {
 * proxy_pass      http://upstream:port/two/;
 * proxy_redirect  http://upstream:port/two/   /one/;

В заменяемой строке можно использовать переменные:
 * proxy_redirect  http://localhost:8000/    http://$host:$server_port/;

Директив может быть несколько:
 * proxy_redirect  default;
 * proxy_redirect  http://localhost:8000/    /;
 * proxy_redirect  http://www.example.com/   /;

Параметр "off" запрещает все директивы proxy_redirect на данном уровне:
 * proxy_redirect  off;
 * proxy_redirect  default;
 * proxy_redirect  http://localhost:8000/    /;
 * proxy_redirect  http://www.example.com/   /;

С помощью этой директивы можно также добавлять имя хоста к относительным редиректам, выдаваемым проксируемым сервером:
 * proxy_redirect  /   /;

proxy_read_timeout
syntax: proxy_read_timeout время

default: proxy_read_timeout 60

context: http, server, location

Директива задаёт таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, то nginx закрывает соединение.

proxy_redirect_errors
syntax: proxy_redirect_errors [on|off] 

Директива переименована в proxy_intercept_errors.

proxy_set_header
syntax: proxy_set_header заголовок значение

default: Host и Connection

context: http, server, location

Директива позволяет переопределять или добавлять строки заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы proxy_set_header. По умолчанию переопределяются только две строки:
 * proxy_set_header Host        $proxy_host;
 * proxy_set_header Connection  close;

Неизменённую строку заголовка запроса "Host" можно передать так:
 * proxy_set_header Host        $http_host;

Однако, если эта строка отсутствует в запросе клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной $host, её значение равно имени сервера в строке заголовка запроса "Host" или же основному имени сервера, если строки нет:
 * proxy_set_header Host        $host;

Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:
 * proxy_set_header Host        $host:$proxy_port;

Если значение строки заголовка — пустая строка, то строка вообще не будет передаваться проксируемому серверу:
 * proxy_set_header Accept-Encoding  "";

Встроенные переменные

В модуле ngx_http_proxy_module есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы proxy_set_header:


 * $proxy_host, эта переменная равна имени проксируемого хоста и порта;
 * $proxy_port, эта переменная равна порту проксируемого хоста;
 * $proxy_add_x_forwarded_for, эта переменная равна строке заголовка запроса клиента "X-Forwarded-For" и добавленной к ней через запятую переменной $remote_addr. Если же строки "X-Forwarded-For" в запросе клиента нет, то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr.