<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_proxy_module"
        link="/ru/docs/http/ngx_http_proxy_module.html"
        lang="ru"
        rev="77">

<section id="summary">

<para>
Модуль <literal>ngx_http_proxy_module</literal> позволяет передавать
запросы другому серверу.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
location / {
    proxy_pass       http://localhost:8000;
    proxy_set_header Host      $host;
    proxy_set_header X-Real-IP $remote_addr;
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="proxy_bind">
<syntax>
    <value>адрес</value>
    [<literal>transparent</literal>] |
    <literal>off</literal></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.8.22</appeared-in>

<para>
Задаёт локальный IP-адрес с необязательным портом (1.11.2),
который будет использоваться в исходящих соединениях с проксируемым сервером.
В значении параметра допустимо использование переменных (1.3.12).
Специальное значение <literal>off</literal> (1.3.12) отменяет действие
унаследованной с предыдущего уровня конфигурации
директивы <literal>proxy_bind</literal>, позволяя системе
самостоятельно выбирать локальный IP-адрес и порт.
</para>

<para id="proxy_bind_transparent">
Параметр <literal>transparent</literal> (1.11.0) позволяет
задать нелокальный IP-aдрес, который будет использоваться в
исходящих соединениях с проксируемым сервером,
например, реальный IP-адрес клиента:
<example>
proxy_bind $remote_addr transparent;
</example>
Для работы параметра
обычно требуется
запустить рабочие процессы nginx с привилегиями
<link doc="../ngx_core_module.xml" id="user">суперпользователя</link>.
В Linux этого не требуется (1.13.8), так как если
указан параметр <literal>transparent</literal>, то рабочие процессы
наследуют capability <literal>CAP_NET_RAW</literal> из главного процесса.
Также необходимо настроить таблицу маршрутизации ядра
для перехвата сетевого трафика с проксируемого сервера.
</para>

</directive>


<directive name="proxy_buffer_size">
<syntax><value>размер</value></syntax>
<default>4k|8k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт <value>размер</value> буфера, в который будет читаться
первая часть ответа, получаемого от проксируемого сервера.
В этой части ответа находится, как правило, небольшой заголовок ответа.
По умолчанию размер одного буфера равен размеру страницы памяти.
В зависимости от платформы это или 4K, или 8K,
однако его можно сделать меньше.
</para>

</directive>


<directive name="proxy_buffering">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает или запрещает использовать буферизацию ответов проксируемого сервера.
</para>

<para>
Если буферизация включена, то nginx принимает ответ проксируемого сервера
как можно быстрее, сохраняя его в буферы, заданные директивами
<link id="proxy_buffer_size"/> и <link id="proxy_buffers"/>.
Если ответ не вмещается целиком в память, то его часть может быть записана
на диск во <link id="proxy_temp_path">временный файл</link>.
Запись во временные файлы контролируется директивами
<link id="proxy_max_temp_file_size"/> и
<link id="proxy_temp_file_write_size"/>.
</para>

<para>
Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же
по мере его поступления.
nginx не пытается считать весь ответ проксируемого сервера.
Максимальный размер данных, который nginx может принять от сервера
за один раз, задаётся директивой <link id="proxy_buffer_size"/>.
</para>

<para>
Буферизация может быть также включена или выключена путём передачи
значения “<literal>yes</literal>” или “<literal>no</literal>” в поле
<header>X-Accel-Buffering</header> заголовка ответа.
Эту возможность можно запретить с помощью директивы
<link id="proxy_ignore_headers"/>.
</para>

</directive>


<directive name="proxy_buffers">
<syntax><value>число</value> <value>размер</value></syntax>
<default>8 4k|8k</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="proxy_busy_buffers_size">
<syntax><value>размер</value></syntax>
<default>8k|16k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
При включённой <link id="proxy_buffering">буферизации</link> ответов
проксируемого сервера, ограничивает суммарный <value>размер</value>
буферов, которые могут быть заняты для отправки ответа клиенту, пока
ответ ещё не прочитан целиком.
Оставшиеся буферы тем временем могут использоваться для чтения ответа
и, при необходимости, буферизации части ответа во временный файл.
По умолчанию <value>размер</value> ограничен величиной двух буферов, заданных
директивами <link id="proxy_buffer_size"/> и <link id="proxy_buffers"/>.
</para>

</directive>


<directive name="proxy_cache">
<syntax><value>зона</value> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт зону разделяемой памяти, используемой для кэширования.
Одна и та же зона может использоваться в нескольких местах.
В значении параметра можно использовать переменные (1.7.9).
Параметр <literal>off</literal> запрещает кэширование, унаследованное
с предыдущего уровня конфигурации.
</para>

</directive>


<directive name="proxy_cache_background_update">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.11.10</appeared-in>

<para>
Позволяет запустить фоновый подзапрос
для обновления просроченного элемента кэша,
в то время как клиенту возвращается устаревший закэшированный ответ.
Использование устаревшего закэшированного ответа в момент его обновления
должно быть
<link id="proxy_cache_use_stale_updating">разрешено</link>.
</para>

</directive>


<directive name="proxy_cache_bypass">
<syntax><value>строка</value> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт условия, при которых ответ не будет браться из кэша.
Если значение хотя бы одного из строковых параметров непустое и не равно “0”,
то ответ не берётся из кэша:
<example>
proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment;
proxy_cache_bypass $http_pragma    $http_authorization;
</example>
Можно использовать совместно с директивой <link id="proxy_no_cache"/>.
</para>

</directive>


<directive name="proxy_cache_convert_head">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.9.7</appeared-in>

<para>
Разрешает или запрещает преобразование метода “<literal>HEAD</literal>”
в “<literal>GET</literal>” для кэширования.
Если преобразование выключено, то
необходимо, чтобы <link id="proxy_cache_key">ключ кэширования</link>
включал в себя <var>$request_method</var>.
</para>

</directive>


<directive name="proxy_cache_key">
<syntax><value>строка</value></syntax>
<default>$scheme$proxy_host$request_uri</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт ключ для кэширования, например,
<example>
proxy_cache_key "$host$request_uri $cookie_user";
</example>
По умолчанию значение директивы близко к строке
<example>
proxy_cache_key $scheme$proxy_host$uri$is_args$args;
</example>
</para>

</directive>


<directive name="proxy_cache_lock">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.12</appeared-in>

<para>
Если включено, одновременно только одному запросу будет позволено
заполнить новый элемент кэша, идентифицируемый согласно директиве
<link id="proxy_cache_key"/>, передав запрос на проксируемый сервер.
Остальные запросы этого же элемента будут либо ожидать
появления ответа в кэше, либо освобождения блокировки
этого элемента, в течение времени, заданного директивой
<link id="proxy_cache_lock_timeout"/>.
</para>

</directive>


<directive name="proxy_cache_lock_age">
<syntax><value>время</value></syntax>
<default>5s</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.8</appeared-in>

<para>
Если последний запрос, переданный на проксируемый сервер
для заполнения нового элемента кэша,
не завершился за указанное <value>время</value>,
на проксируемый сервер может быть передан ещё один запрос.
</para>

</directive>


<directive name="proxy_cache_lock_timeout">
<syntax><value>время</value></syntax>
<default>5s</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.12</appeared-in>

<para>
Задаёт таймаут для <link id="proxy_cache_lock"/>.
По истечении указанного <value>времени</value>
запрос будет передан на проксируемый сервер,
однако ответ не будет закэширован.
<note>
До версии 1.7.8 такой ответ мог быть закэширован.
</note>
</para>

</directive>


<directive name="proxy_cache_max_range_offset">
<syntax><value>число</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.11.6</appeared-in>

<para>
Задаёт смещение в байтах для запросов с указанием диапазона запрашиваемых байт
(byte-range requests).
Если диапазон находится за указанным смещением,
range-запрос будет передан на проксируемый сервер
и ответ не будет закэширован.
</para>

</directive>


<directive name="proxy_cache_methods">
<syntax>
    <literal>GET</literal> |
    <literal>HEAD</literal> |
    <literal>POST</literal>
    ...</syntax>
<default>GET HEAD</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>0.7.59</appeared-in>

<para>
Если метод запроса клиента указан в этой директиве,
то ответ будет закэширован.
Методы “<literal>GET</literal>” и “<literal>HEAD</literal>” всегда добавляются
в список, но тем не менее рекомендуется перечислять их явно.
См. также директиву <link id="proxy_no_cache"/>.
</para>

</directive>


<directive name="proxy_cache_min_uses">
<syntax><value>число</value></syntax>
<default>1</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт <value>число</value> запросов, после которого ответ будет закэширован.
</para>

</directive>


<directive name="proxy_cache_path">
<syntax>
    <value>путь</value>
    [<literal>levels</literal>=<value>уровни</value>]
    [<literal>use_temp_path</literal>=<literal>on</literal>|<literal>off</literal>]
    <literal>keys_zone</literal>=<value>имя</value>:<value>размер</value>
    [<literal>inactive</literal>=<value>время</value>]
    [<literal>max_size</literal>=<value>размер</value>]
    [<literal>min_free</literal>=<value>размер</value>]
    [<literal>manager_files</literal>=<value>число</value>]
    [<literal>manager_sleep</literal>=<value>время</value>]
    [<literal>manager_threshold</literal>=<value>время</value>]
    [<literal>loader_files</literal>=<value>число</value>]
    [<literal>loader_sleep</literal>=<value>время</value>]
    [<literal>loader_threshold</literal>=<value>время</value>]</syntax>
<default/>
<context>http</context>

<para>
Задаёт путь и другие параметры кэша.
Данные кэша хранятся в файлах.
Именем файла в кэше является результат функции MD5
от <link id="proxy_cache_key">ключа кэширования</link>.
Параметр <literal>levels</literal> задаёт уровни иерархии кэша:
можно задать от 1 до 3 уровней, на каждом уровне допускаются значения 1 или 2.
Например, при использовании
<example>
proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m;
</example>
имена файлов в кэше будут такого вида:
<example>
/data/nginx/cache/<emphasis>c</emphasis>/<emphasis>29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis>
</example>
</para>

<para>
Кэшируемый ответ сначала записывается во временный файл, а потом этот файл
переименовывается.
Начиная с версии 0.8.9 временные файлы и кэш
могут располагаться на разных файловых системах.
Однако нужно учитывать,
что в этом случае вместо дешёвой операции переименовывания в пределах
одной файловой системы файл копируется с одной файловой системы на другую.
Поэтому лучше, если кэш будет находиться на той же файловой
системе, что и каталог с временными файлами.
Какой из каталогов будет использоваться для временных файлов
определяется параметром <literal>use_temp_path</literal> (1.7.10).
Если параметр не задан или установлен в значение “<literal>on</literal>”,
то будет использоваться каталог, задаваемый директивой
<link id="proxy_temp_path"/> для данного location.
Если параметр установлен в значение “<literal>off</literal>”,
то временные файлы будут располагаться непосредственно в каталоге кэша.
</para>

<para>
Кроме того, все активные ключи и информация о данных хранятся в зоне
разделяемой памяти, <value>имя</value> и <value>размер</value> которой
задаются параметром <literal>keys_zone</literal>.
Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч ключей.
</para>

<para>
Если к данным кэша не обращаются в течение времени, заданного параметром
<literal>inactive</literal>, то данные удаляются, независимо от их свежести.
По умолчанию <literal>inactive</literal> равен 10 минутам.
</para>

<para id="proxy_cache_path_max_size">
Специальный процесс “cache manager” следит за максимальным размером кэша,
заданным параметром <literal>max_size</literal>,
а также за минимальным объёмом свободного места на файловой системе с кэшем,
заданным параметром <literal>min_free</literal> (1.19.1).
При превышении максимального размера кэша
или недостаточном объёме свободного места
процесс удаляет наименее востребованные данные.
Удаление данных происходит итерациями, настраиваемыми параметрами (1.11.5)
<literal>manager_files</literal>,
<literal>manager_threshold</literal> и
<literal>manager_sleep</literal>.
За одну итерацию загружается не более <literal>manager_files</literal>
элементов (по умолчанию 100).
Время работы одной итерации ограничено параметром
<literal>manager_threshold</literal> (по умолчанию 200 миллисекунд).
Между итерациями делается пауза на время, заданное параметром
<literal>manager_sleep</literal> (по умолчанию 50 миллисекунд).
</para>

<para>
Через минуту после старта активируется специальный процесс “cache loader”,
который загружает в зону кэша информацию о ранее закэшированных данных,
хранящихся на файловой системе.
Загрузка также происходит итерациями.
За одну итерацию загружается не более <literal>loader_files</literal>
элементов (по умолчанию 100).
Кроме того, время работы одной итерации ограничено параметром
<literal>loader_threshold</literal> (по умолчанию 200 миллисекунд).
Между итерациями делается пауза на время, заданное параметром
<literal>loader_sleep</literal> (по умолчанию 50 миллисекунд).
</para>

<para>
<note>
В версиях 1.7.3, 1.7.7 и 1.11.10 формат заголовка кэша был изменён.
При обновлении на более новую версию nginx
ранее закэшированные ответы будут считаться недействительными.
</note>
</para>

</directive>


<directive name="proxy_cache_revalidate">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.7</appeared-in>

<para>
Разрешает ревалидацию просроченных элементов кэша при помощи
условных запросов с полями заголовка
<header>If-Modified-Since</header> и <header>If-None-Match</header>.
</para>

</directive>


<directive name="proxy_cache_use_stale">
<syntax>
    <literal>error</literal> |
    <literal>timeout</literal> |
    <literal>invalid_header</literal> |
    <literal>updating</literal> |
    <literal>http_500</literal> |
    <literal>http_502</literal> |
    <literal>http_503</literal> |
    <literal>http_504</literal> |
    <literal>http_403</literal> |
    <literal>http_404</literal> |
    <literal>http_429</literal> |
    <literal>off</literal>
    ...</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, в каких случаях можно использовать
устаревший закэшированный ответ.
Параметры директивы совпадают с параметрами
директивы <link id="proxy_next_upstream"/>.
</para>

<para>
Параметр <literal>error</literal> также позволяет использовать
устаревший закэшированный ответ при невозможности выбора
проксированного сервера для обработки запроса.
</para>

<para id="proxy_cache_use_stale_updating">
Кроме того, дополнительный параметр <literal>updating</literal>
разрешает использовать устаревший закэшированный ответ,
если на данный момент он уже обновляется.
Это позволяет минимизировать число обращений к проксированным серверам
при обновлении закэшированных данных.
</para>

<para>
Использование устаревшего закэшированного ответа
может также быть разрешено непосредственно в заголовке ответа
на определённое количество секунд после того, как ответ устарел (1.11.10).
Такой способ менее приоритетен, чем задание параметров директивы.
<list type="bullet" compact="no">

<listitem>
Расширение
“<link url="https://datatracker.ietf.org/doc/html/rfc5861#section-3">stale-while-revalidate</link>”
поля заголовка <header>Cache-Control</header> разрешает
использовать устаревший закэшированный ответ,
если на данный момент он уже обновляется.
</listitem>

<listitem>
Расширение
“<link url="https://datatracker.ietf.org/doc/html/rfc5861#section-4">stale-if-error</link>”
поля заголовка <header>Cache-Control</header> разрешает
использовать устаревший закэшированный ответ в случае ошибки.
</listitem>

</list>
</para>

<para>
Чтобы минимизировать число обращений к проксированным серверам при
заполнении нового элемента кэша, можно воспользоваться директивой
<link id="proxy_cache_lock"/>.
</para>

</directive>


<directive name="proxy_cache_valid">
<syntax>[<value>код</value> ...] <value>время</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт время кэширования для разных кодов ответа.
Например, директивы
<example>
proxy_cache_valid 200 302 10m;
proxy_cache_valid 404      1m;
</example>
задают время кэширования 10 минут для ответов с кодами 200 и 302
и 1 минуту для ответов с кодом 404.
</para>

<para>
Если указано только <value>время</value> кэширования,
<example>
proxy_cache_valid 5m;
</example>
то кэшируются только ответы 200, 301 и 302.
</para>

<para>
Кроме того, можно кэшировать любые ответы с помощью параметра
<literal>any</literal>:
<example>
proxy_cache_valid 200 302 10m;
proxy_cache_valid 301      1h;
proxy_cache_valid any      1m;
</example>
</para>

<para>
Параметры кэширования могут также быть заданы непосредственно
в заголовке ответа.
Такой способ приоритетнее, чем задание времени кэширования с помощью директивы.
<list type="bullet" compact="no">

<listitem>
Поле заголовка <header>X-Accel-Expires</header> задаёт время кэширования
ответа в секундах.
Значение 0 запрещает кэшировать ответ.
Если значение начинается с префикса <literal>@</literal>, оно задаёт абсолютное
время в секундах с начала эпохи, до которого ответ может быть закэширован.
</listitem>

<listitem>
Если в заголовке нет поля <header>X-Accel-Expires</header>,
параметры кэширования определяются по полям заголовка
<header>Expires</header> или <header>Cache-Control</header>.
</listitem>

<listitem>
Ответ, в заголовке которого есть поле <header>Set-Cookie</header>,
не будет кэшироваться.
</listitem>

<listitem>
Ответ, в заголовке которого есть поле <header>Vary</header>
со специальным значением “<literal>*</literal>”,
не будет кэшироваться (1.7.7).
Ответ, в заголовке которого есть поле <header>Vary</header>
с другим значением, будет закэширован
с учётом соответствующих полей заголовка запроса (1.7.7).
</listitem>

</list>
Обработка одного или более из этих полей заголовка может быть отключена
при помощи директивы <link id="proxy_ignore_headers"/>.
</para>

</directive>


<directive name="proxy_connect_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут для установления соединения с проксированным сервером.
Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
</para>

</directive>


<directive name="proxy_cookie_domain">
<syntax><literal>off</literal></syntax>
<syntax><value>домен</value> <value>замена</value></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.15</appeared-in>

<para>
Задаёт текст, который нужно изменить в атрибуте <literal>domain</literal>
полей <header>Set-Cookie</header> заголовка ответа проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
<header>Set-Cookie</header> с атрибутом
“<literal>domain=localhost</literal>”.
Директива
<example>
proxy_cookie_domain localhost example.org;
</example>
перепишет данный атрибут в виде
“<literal>domain=example.org</literal>”.
</para>

<para>
Точка в начале строк <value>домен</value> и <value>замена</value>,
а равно как и в атрибуте <literal>domain</literal> игнорируется.
Регистр значения не имеет.
</para>

<para>
В строках <value>домен</value> и <value>замена</value> можно использовать
переменные:
<example>
proxy_cookie_domain www.$host $host;
</example>
</para>

<para>
Директиву также можно задать при помощи регулярных выражений.
При этом <value>домен</value> должен начинаться с символа
“<literal>~</literal>”.
Регулярное выражение может содержать именованные и позиционные выделения,
а <value>замена</value> ссылаться на них:
<example>
proxy_cookie_domain ~\.(?P&lt;sl_domain&gt;[-0-9a-z]+\.[a-z]+)$ $sl_domain;
</example>
</para>

<para>
На одном уровне может быть указано
несколько директив <literal>proxy_cookie_domain</literal>:
<example>
proxy_cookie_domain localhost example.org;
proxy_cookie_domain ~\.([a-z]+\.[a-z]+)$ $1;
</example>
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
</para>

<para>
Параметр <literal>off</literal> отменяет действие
унаследованных с предыдущего уровня конфигурации
директив <literal>proxy_cookie_domain</literal>.
</para>

</directive>


<directive name="proxy_cookie_flags">
<syntax>
    <literal>off</literal> |
    <value>кука</value>
    [<value>флаг</value> ...]</syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.19.3</appeared-in>

<para>
Задаёт один или несколько флагов для куки.
В качестве <value>куки</value>
можно использовать текст, переменные и их комбинации.
В качестве <value>флага</value>
можно использовать текст, переменные и их комбинации (1.19.8).
Параметры
<literal>secure</literal>,
<literal>httponly</literal>,
<literal>samesite=strict</literal>,
<literal>samesite=lax</literal>,
<literal>samesite=none</literal>
добавляют соответствующие флаги.
Параметры
<literal>nosecure</literal>,
<literal>nohttponly</literal>,
<literal>nosamesite</literal>
удаляют соответствующие флаги.
</para>

<para>
Куки также можно задать при помощи регулярных выражений.
При этом <value>кука</value> должна начинаться с символа
“<literal>~</literal>”.
</para>

<para>
На одном уровне конфигурации может быть указано
несколько директив <literal>proxy_cookie_flags</literal>:
<example>
proxy_cookie_flags one httponly;
proxy_cookie_flags ~ nosecure samesite=strict;
</example>
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
В данном примере флаг <literal>httponly</literal>
добавляется к куке <literal>one</literal>,
для остальных кук
добавляется флаг <literal>samesite=strict</literal> и
удаляется флаг <literal>secure</literal>.
</para>

<para>
Параметр <literal>off</literal> отменяет действие всех директив
<literal>proxy_cookie_flags</literal>
на данном уровне.
</para>

</directive>


<directive name="proxy_cookie_path">
<syntax><literal>off</literal></syntax>
<syntax><value>путь</value> <value>замена</value></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.15</appeared-in>

<para>
Задаёт текст, который нужно изменить в атрибуте <literal>path</literal>
полей <header>Set-Cookie</header> заголовка ответа проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
<header>Set-Cookie</header> с атрибутом
“<literal>path=/two/some/uri/</literal>”.
Директива
<example>
proxy_cookie_path /two/ /;
</example>
перепишет данный атрибут в виде
“<literal>path=/some/uri/</literal>”.
</para>

<para>
В строках <value>путь</value> и <value>замена</value> можно использовать
переменные:
<example>
proxy_cookie_path $uri /some$uri;
</example>
</para>

<para>
Директиву также можно задать при помощи регулярных выражений.
При этом <value>путь</value> должен начинаться либо с символа
“<literal>~</literal>”, если при сравнении следует учитывать регистр символов,
либо с символов “<literal>~*</literal>”, если регистр символов учитывать
не нужно.
Регулярное выражение может содержать именованные и позиционные выделения,
а <value>замена</value> ссылаться на них:
<example>
proxy_cookie_path ~*^/user/([^/]+) /u/$1;
</example>
</para>

<para>
На одном уровне может быть указано
несколько директив <literal>proxy_cookie_path</literal>:
<example>
proxy_cookie_path /one/ /;
proxy_cookie_path / /two/;
</example>
Если к куке могут быть применены несколько директив,
будет выбрана первая из них.
</para>

<para>
Параметр <literal>off</literal> отменяет действие
унаследованных с предыдущего уровня конфигурации
директив <literal>proxy_cookie_path</literal>.
</para>

</directive>


<directive name="proxy_force_ranges">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.7</appeared-in>

<para>
Включает поддержку диапазонов запрашиваемых байт (byte-range)
для кэшированных и некэшированных ответов проксируемого сервера
вне зависимости от наличия поля <header>Accept-Ranges</header>
в заголовках этих ответов.
</para>

</directive>


<directive name="proxy_headers_hash_bucket_size">
<syntax><value>размер</value></syntax>
<default>64</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт <value>размер</value> корзины для хэш-таблиц,
используемых директивами <link id="proxy_hide_header"/>
и <link id="proxy_set_header"/>.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="proxy_headers_hash_max_size">
<syntax><value>размер</value></syntax>
<default>512</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт максимальный <value>размер</value> хэш-таблиц,
используемых директивами <link id="proxy_hide_header"/> и
<link id="proxy_set_header"/>.
Подробнее настройка хэш-таблиц обсуждается в отдельном
<link doc="../hash.xml">документе</link>.
</para>

</directive>


<directive name="proxy_hide_header">
<syntax><value>поле</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
По умолчанию
nginx не передаёт клиенту поля заголовка <header>Date</header>,
<header>Server</header>, <header>X-Pad</header> и
<header>X-Accel-...</header> из ответа проксированного сервера.
Директива <literal>proxy_hide_header</literal> задаёт дополнительные поля,
которые не будут передаваться.
Если же передачу полей нужно разрешить, можно воспользоваться
директивой <link id="proxy_pass_header"/>.
</para>

</directive>


<directive name="proxy_http_version">
<syntax><literal>1.0</literal> | <literal>1.1</literal></syntax>
<default>1.0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.1.4</appeared-in>

<para>
Задаёт версию протокола HTTP для проксирования.
По умолчанию используется версия 1.0.
Для работы
<link doc="ngx_http_upstream_module.xml" id="keepalive">постоянных
соединений</link> и
<link doc="ngx_http_upstream_module.xml" id="ntlm">проверки подлинности
NTLM</link> рекомендуется версия 1.1.
</para>

</directive>


<directive name="proxy_ignore_client_abort">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, закрывать ли соединение с проксированным сервером
в случае, если клиент закрыл соединение, не дождавшись ответа.
</para>

</directive>


<directive name="proxy_ignore_headers">
<syntax><value>поле</value> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Запрещает обработку некоторых полей заголовка из ответа проксированного сервера.
В директиве можно указать поля <header>X-Accel-Redirect</header>,
<header>X-Accel-Expires</header>, <header>X-Accel-Limit-Rate</header> (1.1.6),
<header>X-Accel-Buffering</header> (1.1.6),
<header>X-Accel-Charset</header> (1.1.6), <header>Expires</header>,
<header>Cache-Control</header>, <header>Set-Cookie</header> (0.8.44)
и <header>Vary</header> (1.7.7).
</para>

<para>
Если не запрещено, обработка этих полей заголовка заключается в следующем:
<list type="bullet" compact="no">

<listitem>
<header>X-Accel-Expires</header>, <header>Expires</header>,
<header>Cache-Control</header>, <header>Set-Cookie</header>
и <header>Vary</header>
задают параметры <link id="proxy_cache_valid">кэширования</link> ответа;
</listitem>

<listitem>
<header>X-Accel-Redirect</header> производит
<link doc="ngx_http_core_module.xml" id="internal">внутреннее
перенаправление</link> на указанный URI;
</listitem>

<listitem>
<header>X-Accel-Limit-Rate</header> задаёт
<link doc="ngx_http_core_module.xml" id="limit_rate">ограничение
скорости</link> передачи ответа клиенту;
</listitem>

<listitem>
<header>X-Accel-Buffering</header> включает или выключает
<link id="proxy_buffering">буферизацию</link> ответа;
</listitem>

<listitem>
<header>X-Accel-Charset</header> задаёт желаемую
<link doc="ngx_http_charset_module.xml" id="charset">кодировку</link>
ответа.
</listitem>

</list>
</para>

</directive>


<directive name="proxy_intercept_errors">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, передавать ли клиенту проксированные ответы с кодом
больше либо равным 300,
или же перехватывать их и перенаправлять на обработку nginx’у с помощью
директивы <link doc="ngx_http_core_module.xml" id="error_page"/>.
</para>

</directive>


<directive name="proxy_limit_rate">
<syntax><value>скорость</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.7</appeared-in>

<para>
Ограничивает скорость чтения ответа от проксируемого сервера.
<value>Скорость</value> задаётся в байтах в секунду.
Значение 0 отключает ограничение скорости.
Ограничение устанавливается на запрос,
поэтому, если nginx одновременно
откроет два соединения к проксируемому серверу,
суммарная скорость будет вдвое выше заданного ограничения.
Ограничение работает только в случае, если включена
<link id="proxy_buffering">буферизация</link> ответов проксируемого сервера.
</para>

</directive>


<directive name="proxy_max_temp_file_size">
<syntax><value>размер</value></syntax>
<default>1024m</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Если включена <link id="proxy_buffering">буферизация</link> ответов
проксируемого сервера, и ответ не вмещается целиком в буферы,
заданные директивами <link id="proxy_buffer_size"/> и
<link id="proxy_buffers"/>, часть ответа может быть записана во временный файл.
Эта директива задаёт максимальный <value>размер</value> временного файла.
Размер данных, сбрасываемых во временный файл за один раз, задаётся
директивой <link id="proxy_temp_file_write_size"/>.
</para>

<para>
Значение 0 отключает возможность буферизации ответов во временные файлы.
</para>

<para>
<note>
Данное ограничение не распространяется на ответы,
которые будут <link id="proxy_cache">закэшированы</link>
или <link id="proxy_store">сохранены</link> на диске.
</note>
</para>

</directive>


<directive name="proxy_method">
<syntax><value>метод</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт HTTP-<value>метод</value>, который будет использоваться
в передаваемых на проксируемый сервер запросах вместо метода
из клиентского запроса.
В значении параметра допустимо использование переменных (1.11.6).
</para>

</directive>


<directive name="proxy_next_upstream">
<syntax>
    <literal>error</literal> |
    <literal>timeout</literal> |
    <literal>invalid_header</literal> |
    <literal>http_500</literal> |
    <literal>http_502</literal> |
    <literal>http_503</literal> |
    <literal>http_504</literal> |
    <literal>http_403</literal> |
    <literal>http_404</literal> |
    <literal>http_429</literal> |
    <literal>non_idempotent</literal> |
    <literal>off</literal>
    ...</syntax>
<default>error timeout</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, в каких случаях запрос будет передан следующему серверу:
<list type="tag">

<tag-name><literal>error</literal></tag-name>
<tag-desc>произошла ошибка соединения с сервером, передачи ему запроса или
чтения заголовка ответа сервера;</tag-desc>

<tag-name><literal>timeout</literal></tag-name>
<tag-desc>произошёл таймаут во время соединения с сервером,
передачи ему запроса или чтения заголовка ответа сервера;</tag-desc>

<tag-name><literal>invalid_header</literal></tag-name>
<tag-desc>сервер вернул пустой или неверный ответ;</tag-desc>

<tag-name><literal>http_500</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 500;</tag-desc>

<tag-name><literal>http_502</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 502;</tag-desc>

<tag-name><literal>http_503</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 503;</tag-desc>

<tag-name><literal>http_504</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 504;</tag-desc>

<tag-name><literal>http_403</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 403;</tag-desc>

<tag-name><literal>http_404</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 404;</tag-desc>

<tag-name><literal>http_429</literal></tag-name>
<tag-desc>сервер вернул ответ с кодом 429 (1.11.13);</tag-desc>

<tag-name id="non_idempotent"><literal>non_idempotent</literal></tag-name>
<tag-desc>обычно запросы с
<link url="https://datatracker.ietf.org/doc/html/rfc7231#section-4.2.2">неидемпотентным</link>
методом
(<literal>POST</literal>, <literal>LOCK</literal>, <literal>PATCH</literal>)
не передаются на другой сервер,
если запрос серверу группы уже был отправлен (1.9.13);
включение параметра явно разрешает повторять подобные запросы;
</tag-desc>


<tag-name><literal>off</literal></tag-name>
<tag-desc>запрещает передачу запроса следующему серверу.</tag-desc>

</list>
</para>

<para>
Необходимо понимать, что передача запроса следующему серверу возможна
только при условии, что клиенту ещё ничего не передавалось.
То есть, если ошибка или таймаут возникли в середине передачи ответа
клиенту, то исправить это уже невозможно.
</para>

<para>
Директива также определяет, что считается
<link doc="ngx_http_upstream_module.xml" id="max_fails">неудачной
попыткой</link> работы с сервером.
Случаи <literal>error</literal>, <literal>timeout</literal> и
<literal>invalid_header</literal>
всегда считаются неудачными попытками, даже если они не указаны в директиве.
Случаи <literal>http_500</literal>, <literal>http_502</literal>,
<literal>http_503</literal>, <literal>http_504</literal>
и <literal>http_429</literal>
считаются неудачными попытками, только если они указаны в директиве.
Случаи <literal>http_403</literal> и <literal>http_404</literal>
никогда не считаются неудачными попытками.
</para>

<para>
Передача запроса следующему серверу может быть ограничена по
<link id="proxy_next_upstream_tries">количеству попыток</link>
и по <link id="proxy_next_upstream_timeout">времени</link>.
</para>

</directive>


<directive name="proxy_next_upstream_timeout">
<syntax><value>время</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Ограничивает время, в течение которого возможна передача запроса
<link id="proxy_next_upstream">следующему серверу</link>.
Значение <literal>0</literal> отключает это ограничение.
</para>

</directive>


<directive name="proxy_next_upstream_tries">
<syntax><value>число</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.5</appeared-in>

<para>
Ограничивает число допустимых попыток для передачи запроса
<link id="proxy_next_upstream">следующему серверу</link>.
Значение <literal>0</literal> отключает это ограничение.
</para>

</directive>


<directive name="proxy_no_cache">
<syntax><value>строка</value> ...</syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт условия, при которых ответ не будет сохраняться в кэш.
Если значение хотя бы одного из строковых параметров непустое и не равно “0”,
то ответ не будет сохранён:
<example>
proxy_no_cache $cookie_nocache $arg_nocache$arg_comment;
proxy_no_cache $http_pragma    $http_authorization;
</example>
Можно использовать совместно с директивой <link id="proxy_cache_bypass"/>.
</para>

</directive>


<directive name="proxy_pass">
<syntax><value>URL</value></syntax>
<default/>
<context>location</context>
<context>if в location</context>
<context>limit_except</context>

<para>
Задаёт протокол и адрес проксируемого сервера, а также необязательный URI,
на который должен отображаться location.
В качестве протокола можно указать
“<literal>http</literal>” или “<literal>https</literal>”.
Адрес может быть указан в виде доменного имени или IP-адреса,
и необязательного порта:
<example>
proxy_pass http://localhost:8000/uri/;
</example>
или в виде пути UNIX-сокета, который указывается после слова
“<literal>unix</literal>” и заключается в двоеточия:
<example>
proxy_pass http://unix:/tmp/backend.socket:/uri/;
</example>
</para>

<para>
Если доменному имени соответствует несколько адресов, то все они будут
использоваться по очереди (round-robin).
Кроме того, в качестве адреса можно указать
<link doc="ngx_http_upstream_module.xml">группу серверов</link>.
</para>

<para>
В значении параметра можно использовать переменные.
В этом случае, если адрес указан в виде доменного имени,
имя ищется среди описанных групп серверов
и если не найдено, то определяется с помощью
<link doc="ngx_http_core_module.xml" id="resolver"/>’а.
</para>

<para>
URI запроса передаётся на сервер так:
<list type="bullet" compact="no">

<listitem>
Если директива <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>
Если директива <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 задан регулярным выражением,
а также в именованных location’ах.
<para>
В этих случаях
<literal>proxy_pass</literal> следует указывать без URI.
</para>
</listitem>

<listitem>
Если внутри проксируемого location с помощью директивы
<link doc="ngx_http_rewrite_module.xml" id="rewrite"/> изменяется
URI, и именно с этой конфигурацией будет обрабатываться запрос
(<literal>break</literal>):
<example>
location /name/ {
    rewrite    /name/([^/]+) /users?name=$1 break;
    proxy_pass http://127.0.0.1;
}
</example>
<para>
В этом случае URI, указанный в директиве, игнорируется, и на сервер
передаётся изменённый URI запроса целиком.
</para>
</listitem>

<listitem>
При использовании переменных в <literal>proxy_pass</literal>:
<example>
location /name/ {
    proxy_pass http://127.0.0.1$request_uri;
}
</example>
В этом случае если в директиве указан URI,
он передаётся на сервер как есть,
заменяя URI первоначального запроса.
</listitem>
</list>
</para>

<para>
Проксирование <link doc="websocket.xml">WebSocket</link> требует особой
настройки и поддерживается начиная с версии 1.3.13.
</para>

</directive>


<directive name="proxy_pass_header">
<syntax><value>поле</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает передавать от проксируемого сервера клиенту
<link id="proxy_hide_header">запрещённые для передачи</link> поля заголовка.
</para>

</directive>


<directive name="proxy_pass_request_body">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет запретить передачу исходного тела запроса
на проксируемый сервер.
<example>
location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";

    proxy_pass ...
}
</example>
См. также директивы <link id="proxy_set_header"/> и
<link id="proxy_pass_request_headers"/>.
</para>

</directive>


<directive name="proxy_pass_request_headers">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет запретить передачу полей заголовка исходного запроса на
проксируемый сервер.
<example>
location /x-accel-redirect-here/ {
    proxy_method GET;
    proxy_pass_request_headers off;
    proxy_pass_request_body off;

    proxy_pass ...
}
</example>
См. также директивы <link id="proxy_set_header"/> и
<link id="proxy_pass_request_body"/>.
</para>

</directive>


<directive name="proxy_read_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="proxy_redirect">
<syntax><literal>default</literal></syntax>
<syntax><literal>off</literal></syntax>
<syntax><value>перенаправление</value> <value>замена</value></syntax>
<default>default</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт текст, который нужно изменить в полях заголовка
<header>Location</header> и <header>Refresh</header> в ответе
проксируемого сервера.
Предположим, проксируемый сервер вернул поле заголовка
“<literal>Location: http://localhost:8000/two/some/uri/</literal>”.
Директива
<example>
proxy_redirect http://localhost:8000/two/ http://frontend/one/;
</example>
перепишет эту строку в виде
“<literal>Location: http://frontend/one/some/uri/</literal>”.
</para>

<para>
В заменяемой строке можно не указывать имя сервера:
<example>
proxy_redirect http://localhost:8000/two/ /;
</example>
тогда будут подставлены основное имя сервера и порт, если он отличен от 80.
</para>

<para>
Стандартная замена, задаваемая параметром <literal>default</literal>,
использует параметры директив
<link doc="ngx_http_core_module.xml" id="location"/> и
<link id="proxy_pass"/>.
Поэтому две нижеприведённые конфигурации одинаковы:
<example>
location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect default;
</example>

<example>
location /one/ {
    proxy_pass     http://upstream:port/two/;
    proxy_redirect http://upstream:port/two/ /one/;
</example>
Параметр <literal>default</literal> недопустим, если в <link id="proxy_pass"/>
используются переменные.
</para>

<para>
В строке <value>замена</value> можно использовать переменные:
<example>
proxy_redirect http://localhost:8000/ http://$host:$server_port/;
</example>
</para>

<para>
В строке <value>перенаправление</value> тоже можно использовать (1.1.11)
переменные:
<example>
proxy_redirect http://$proxy_host:8000/ /;
</example>
</para>

<para>
Директиву также можно задать (1.1.11) при помощи регулярных выражений.
При этом <value>перенаправление</value> должно начинаться либо с символа
“<literal>~</literal>”, если при сравнении следует учитывать регистр символов,
либо с символов “<literal>~*</literal>”, если регистр символов учитывать
не нужно.
Регулярное выражение может содержать именованные и позиционные выделения,
а <value>замена</value> ссылаться на них:
<example>
proxy_redirect ~^(http://[^:]+):\d+(/.+)$ $1$2;
proxy_redirect ~*/user/([^/]+)/(.+)$      http://$1.example.com/$2;
</example>
</para>

<para>
На одном уровне может быть указано
несколько директив <literal>proxy_redirect</literal>:
<example>
proxy_redirect default;
proxy_redirect http://localhost:8000/  /;
proxy_redirect http://www.example.com/ /;
</example>
Если к полям заголовка в ответе проксируемого сервера
могут быть применены несколько директив,
будет выбрана первая из них.
</para>

<para>
Параметр <literal>off</literal> отменяет действие
унаследованных с предыдущего уровня конфигурации
директив <literal>proxy_redirect</literal>.
</para>

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

</directive>


<directive name="proxy_request_buffering">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.11</appeared-in>

<para>
Разрешает или запрещает использовать буферизацию тела запроса клиента.
</para>

<para>
Если буферизация включена, то тело запроса полностью
<link doc="ngx_http_core_module.xml" id="client_body_buffer_size">читается</link>
от клиента перед отправкой запроса на проксируемый сервер.
</para>

<para>
Если буферизация выключена, то тело запроса отправляется
на проксируемый сервер сразу же по мере его поступления.
В этом случае запрос не может быть передан
<link id="proxy_next_upstream">следующему серверу</link>,
если nginx уже начал отправку тела запроса.
</para>

<para>
Если для отправки тела исходного запроса используется HTTP/1.1
и передача данных частями (chunked transfer encoding),
то тело запроса буферизуется независимо от значения директивы,
если для проксирования также не
<link id="proxy_http_version">включён</link> HTTP/1.1.
</para>

</directive>


<directive name="proxy_send_lowat">
<syntax><value>размер</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
При установке директивы в ненулевое значение nginx будет пытаться минимизировать
число операций отправки на исходящих соединениях с проксируемым сервером либо
при помощи флага <c-def>NOTE_LOWAT</c-def> метода
<link doc="../events.xml" id="kqueue"/>,
либо при помощи параметра сокета <c-def>SO_SNDLOWAT</c-def>,
с указанным <value>размером</value>.
</para>

<para>
Эта директива игнорируется на Linux, Solaris и Windows.
</para>

</directive>


<directive name="proxy_send_timeout">
<syntax><value>время</value></syntax>
<default>60s</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт таймаут при передаче запроса проксированному серверу.
Таймаут устанавливается не на всю передачу запроса,
а только между двумя операциями записи.
Если по истечении этого времени проксируемый сервер не примет новых данных,
соединение закрывается.
</para>

</directive>


<directive name="proxy_set_body">
<syntax><value>значение</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет переопределить тело запроса, передаваемое на проксируемый сервер.
В качестве значения можно использовать текст, переменные и их комбинации.
</para>

</directive>


<directive name="proxy_set_header">
<syntax><value>поле</value> <value>значение</value></syntax>
<default>Host $proxy_host</default>
<default>Connection close</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет переопределять или добавлять поля заголовка запроса,
<link id="proxy_pass_request_headers">передаваемые</link> проксируемому серверу.
В качестве значения можно использовать текст, переменные и их комбинации.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>proxy_set_header</literal>.
По умолчанию переопределяются только два поля:
<example>
proxy_set_header Host       $proxy_host;
proxy_set_header Connection close;
</example>
Если включено кэширование, поля заголовка
<header>If-Modified-Since</header>,
<header>If-Unmodified-Since</header>,
<header>If-None-Match</header>,
<header>If-Match</header>,
<header>Range</header>
и
<header>If-Range</header>
исходного запроса не передаются на проксируемый сервер.
</para>

<para>
Неизменённое поле заголовка запроса <header>Host</header> можно передать так:
<example>
proxy_set_header Host       $http_host;
</example>
</para>

<para>
Однако, если это поле отсутствует в заголовке запроса клиента, то ничего
передаваться не будет.
В этом случае лучше воспользоваться переменной <var>$host</var>&mdash;её
значение равно имени сервера в поле <header>Host</header>
заголовка запроса, или же основному имени сервера, если поля нет:
<example>
proxy_set_header Host       $host;
</example>
</para>

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

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

</directive>


<directive name="proxy_socket_keepalive">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.15.6</appeared-in>

<para>
Конфигурирует поведение “TCP keepalive”
для исходящих соединений к проксируемому серверу.
По умолчанию для сокета действуют настройки операционной системы.
Если указано значение “<literal>on</literal>”, то
для сокета включается параметр <c-def>SO_KEEPALIVE</c-def>.
</para>

</directive>


<directive name="proxy_ssl_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.8</appeared-in>

<para>
Задаёт <value>файл</value> с сертификатом в формате PEM
для аутентификации на проксируемом HTTPS-сервере.
</para>

<para>
Начиная с версии 1.21.0 в имени файла можно использовать переменные.
</para>

</directive>


<directive name="proxy_ssl_certificate_key">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.8</appeared-in>

<para>
Задаёт <value>файл</value> с секретным ключом в формате PEM
для аутентификации на проксируемом HTTPS-сервере.
</para>

<para>
Вместо <value>файла</value> можно указать значение
<literal>engine</literal>:<value>имя</value>:<value>id</value> (1.7.9),
которое загружает ключ с указанным <value>id</value>
из OpenSSL engine с заданным <value>именем</value>.
</para>

<para>
Начиная с версии 1.21.0 в имени файла можно использовать переменные.
</para>

</directive>


<directive name="proxy_ssl_ciphers">
<syntax><value>шифры</value></syntax>
<default>DEFAULT</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.6</appeared-in>

<para>
Описывает разрешённые шифры для запросов к проксируемому HTTPS-серверу.
Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
</para>

<para>
Полный список можно посмотреть с помощью команды
“<command>openssl ciphers</command>”.
</para>

</directive>


<directive name="proxy_ssl_conf_command">
<syntax><value>имя</value> <value>значение</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.19.4</appeared-in>

<para>
Задаёт произвольные конфигурационные
<link url="https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html">команды</link>
OpenSSL
при установлении соединения с проксируемым HTTPS-сервером.
<note>
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
</note>
</para>

<para>
На одном уровне может быть указано
несколько директив <literal>proxy_ssl_conf_command</literal>.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны
свои директивы <literal>proxy_ssl_conf_command</literal>.
</para>

<para>
<note>
Следует учитывать, что изменение настроек OpenSSL напрямую
может привести к неожиданному поведению.
</note>
</para>

</directive>


<directive name="proxy_ssl_crl">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Указывает <value>файл</value> с отозванными сертификатами (CRL)
в формате PEM, используемыми при <link id="proxy_ssl_verify">проверке</link>
сертификата проксируемого HTTPS-сервера.
</para>

</directive>


<directive name="proxy_ssl_name">
<syntax><value>имя</value></syntax>
<default>$proxy_host</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Позволяет переопределить имя сервера, используемое при
<link id="proxy_ssl_verify">проверке</link>
сертификата проксируемого HTTPS-сервера, а также для
<link id="proxy_ssl_server_name">передачи его через SNI</link>
при установлении соединения с проксируемым HTTPS-сервером.
</para>

<para>
По умолчанию используется имя хоста из URL’а, заданного
директивой <link id="proxy_pass"/>.
</para>

</directive>


<directive name="proxy_ssl_password_file">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.8</appeared-in>

<para>
Задаёт <value>файл</value> с паролями от
<link id="proxy_ssl_certificate_key">секретных ключей</link>,
где каждый пароль указан на отдельной строке.
Пароли применяются по очереди в момент загрузки ключа.
</para>

</directive>


<directive name="proxy_ssl_protocols">
<syntax>
    [<literal>SSLv2</literal>]
    [<literal>SSLv3</literal>]
    [<literal>TLSv1</literal>]
    [<literal>TLSv1.1</literal>]
    [<literal>TLSv1.2</literal>]
    [<literal>TLSv1.3</literal>]</syntax>
<default>TLSv1 TLSv1.1 TLSv1.2 TLSv1.3</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.5.6</appeared-in>

<para>
Разрешает указанные протоколы для запросов к проксируемому HTTPS-серверу.
</para>

<para>
<note>
Параметр <literal>TLSv1.3</literal> используется по умолчанию
начиная с 1.23.4.
</note>
</para>

</directive>


<directive name="proxy_ssl_server_name">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Разрешает или запрещает передачу имени сервера через
<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">расширение
Server Name Indication протокола TLS</link> (SNI, RFC 6066)
при установлении соединения с проксируемым HTTPS-сервером.
</para>

</directive>


<directive name="proxy_ssl_session_reuse">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>on</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Определяет, использовать ли повторно SSL-сессии при
работе с проксированным сервером.
Если в логах появляются ошибки
“<literal>SSL3_GET_FINISHED:digest check failed</literal>”,
то можно попробовать выключить
повторное использование сессий.
</para>

</directive>


<directive name="proxy_ssl_trusted_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM,
используемыми при <link id="proxy_ssl_verify">проверке</link>
сертификата проксируемого HTTPS-сервера.
</para>

</directive>


<directive name="proxy_ssl_verify">
<syntax><literal>on</literal> | <literal>off</literal></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Разрешает или запрещает проверку сертификата проксируемого HTTPS-сервера.
</para>

</directive>


<directive name="proxy_ssl_verify_depth">
<syntax><value>число</value></syntax>
<default>1</default>
<context>http</context>
<context>server</context>
<context>location</context>
<appeared-in>1.7.0</appeared-in>

<para>
Устанавливает глубину проверки в цепочке сертификатов
проксируемого HTTPS-сервера.
</para>

</directive>


<directive name="proxy_store">
<syntax>
    <literal>on</literal> |
    <literal>off</literal> |
    <value>строка</value></syntax>
<default>off</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Разрешает сохранение на диск файлов.
Параметр <literal>on</literal> сохраняет файлы в соответствии с путями,
указанными в директивах
<link doc="ngx_http_core_module.xml" id="alias"/> или
<link doc="ngx_http_core_module.xml" id="root"/>.
Параметр <literal>off</literal> запрещает сохранение файлов.
Кроме того, имя файла можно задать явно с помощью строки с переменными:
<example>
proxy_store /data/www$original_uri;
</example>
</para>

<para>
Время изменения файлов выставляется согласно полученному полю
<header>Last-Modified</header> в заголовке ответа.
Ответ сначала записывается во временный файл, а потом этот файл
переименовывается.
Начиная с версии 0.8.9 временный файл и постоянное место хранения ответа
могут располагаться на разных файловых системах.
Однако нужно учитывать,
что в этом случае вместо дешёвой операции переименовывания в пределах
одной файловой системы файл копируется с одной файловой системы на другую.
Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой
системе, что и каталог с временными файлами, задаваемый директивой
<link id="proxy_temp_path"/> для данного location.
</para>

<para>
Директиву можно использовать для создания локальных копий статических
неизменяемых файлов, например, так:
<example>
location /images/ {
    root               /data/www;
    error_page         404 = /fetch$uri;
}

location /fetch/ {
    internal;

    proxy_pass         http://backend/;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    alias              /data/www/;
}
</example>
</para>

<para>
или так:
<example>
location /images/ {
    root               /data/www;
    error_page         404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass         http://backend;
    proxy_store        on;
    proxy_store_access user:rw group:rw all:r;
    proxy_temp_path    /data/temp;

    root               /data/www;
}
</example>
</para>

</directive>


<directive name="proxy_store_access">
<syntax><value>пользователи</value>:<value>права</value> ...</syntax>
<default>user:rw</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт права доступа для создаваемых файлов и каталогов, например,
<example>
proxy_store_access user:rw group:rw all:r;
</example>
</para>

<para>
Если заданы какие-либо права для <literal>group</literal> или
<literal>all</literal>, то права для <literal>user</literal>
указывать необязательно:
<example>
proxy_store_access group:rw all:r;
</example>
</para>

</directive>


<directive name="proxy_temp_file_write_size">
<syntax><value>размер</value></syntax>
<default>8k|16k</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Ограничивает <value>размер</value> данных, сбрасываемых во временный файл
за один раз, при включённой буферизации ответов проксируемого сервера
во временные файлы.
По умолчанию <value>размер</value> ограничен двумя буферами, заданными
директивами <link id="proxy_buffer_size"/> и <link id="proxy_buffers"/>.
Максимальный размер временного файла задаётся директивой
<link id="proxy_max_temp_file_size"/>.
</para>

</directive>


<directive name="proxy_temp_path">
<syntax>
    <value>путь</value>
    [<value>уровень1</value>
    [<value>уровень2</value>
    [<value>уровень3</value>]]]</syntax>
<default>proxy_temp</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Задаёт имя каталога для хранения временных файлов с данными,
полученными от проксируемых серверов.
В каталоге может использоваться иерархия подкаталогов до трёх уровней.
Например, при такой конфигурации
<example>
proxy_temp_path /spool/nginx/proxy_temp 1 2;
</example>
временный файл будет следующего вида:
<example>
/spool/nginx/proxy_temp/<emphasis>7</emphasis>/<emphasis>45</emphasis>/00000123<emphasis>457</emphasis>
</example>
</para>

<para>
См. также параметр <literal>use_temp_path</literal> директивы
<link id="proxy_cache_path"/>.
</para>

</directive>

</section>


<section id="variables" name="Встроенные переменные">

<para>
В модуле <literal>ngx_http_proxy_module</literal> есть встроенные переменные,
которые можно использовать для формирования заголовков с помощью директивы
<link id="proxy_set_header"/>:
<list type="tag">

<tag-name id="var_proxy_host"><var>$proxy_host</var></tag-name>
<tag-desc>имя и порт проксируемого сервера, как указано в
директиве <link id="proxy_pass"/>;</tag-desc>

<tag-name id="var_proxy_port"><var>$proxy_port</var></tag-name>
<tag-desc>порт проксируемого сервера, как указано в
директиве <link id="proxy_pass"/>, или стандартный порт протокола;</tag-desc>

<tag-name id="var_proxy_add_x_forwarded_for">
<var>$proxy_add_x_forwarded_for</var></tag-name>
<tag-desc>поле заголовка запроса клиента <header>X-Forwarded-For</header>
и добавленная к нему через запятую переменная <var>$remote_addr</var>.
Если же поля <header>X-Forwarded-For</header> в заголовке запроса клиента нет,
то переменная <var>$proxy_add_x_forwarded_for</var>
равна переменной <var>$remote_addr</var>.</tag-desc>
</list>
</para>

</section>

</module>