<?xml version="1.0"?>

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

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

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

<section id="summary">

<para>
Модуль <literal>ngx_http_grpc_module</literal> позволяет передавать запросы
gRPC-серверу (1.13.10).
Для работы этого модуля необходим
модуль <link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link>.
</para>

</section>


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

<para>
<example>
server {
    listen 9000 http2;

    location / {
        grpc_pass 127.0.0.1:9000;
    }
}
</example>
</para>

</section>


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

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

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

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

</directive>


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

<para>
Задаёт <value>размер</value> буфера, в который будет читаться ответ,
получаемый от gRPC-сервера.
Ответ синхронно передаётся клиенту сразу же по мере его поступления.
</para>

</directive>


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

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

</directive>


<directive name="grpc_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-Accel-...</header> из ответа gRPC-сервера.
Директива <literal>grpc_hide_header</literal> задаёт дополнительные поля,
которые не будут передаваться.
Если же передачу полей нужно разрешить, можно воспользоваться
директивой <link id="grpc_pass_header"/>.
</para>

</directive>


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

<para>
Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера.
В директиве можно указать поля <header>X-Accel-Redirect</header>
и <header>X-Accel-Charset</header>.
</para>

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

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

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

</list>
</para>

</directive>


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

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

</directive>


<directive name="grpc_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;</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>)
не передаются на другой сервер,
если запрос серверу группы уже был отправлен;
включение параметра явно разрешает повторять подобные запросы;
</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="grpc_next_upstream_tries">количеству попыток</link>
и по <link id="grpc_next_upstream_timeout">времени</link>.
</para>

</directive>


<directive name="grpc_next_upstream_timeout">
<syntax><value>время</value></syntax>
<default>0</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


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

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

</directive>


<directive name="grpc_pass">
<syntax><value>адрес</value></syntax>
<default/>
<context>location</context>
<context>if в location</context>

<para>
Задаёт адрес gRPC-сервера.
Адрес может быть указан в виде доменного имени или IP-адреса,
и порта:
<example>
grpc_pass localhost:9000;
</example>
или в виде пути UNIX-сокета:
<example>
grpc_pass unix:/tmp/grpc.socket;
</example>
Также может использоваться схема “<literal>grpc://</literal>”:
<example>
grpc_pass grpc://127.0.0.1:9000;
</example>
Для использования gRPC по SSL необходимо использовать схему
“<literal>grpcs://</literal>”:
<example>
grpc_pass grpcs://127.0.0.1:443;
</example>
</para>

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

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

</directive>


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

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

</directive>


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

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

</directive>


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

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

</directive>


<directive name="grpc_set_header">
<syntax><value>поле</value> <value>значение</value></syntax>
<default>Content-Length $content_length</default>
<context>http</context>
<context>server</context>
<context>location</context>

<para>
Позволяет переопределять или добавлять поля заголовка запроса,
<link id="proxy_pass_request_headers">передаваемые</link> gRPC-серверу.
В качестве значения можно использовать текст, переменные и их комбинации.
Директивы наследуются с предыдущего уровня конфигурации при условии, что
на данном уровне не описаны свои директивы <literal>grpc_set_header</literal>.
</para>

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

</directive>


<directive name="grpc_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”
для исходящих соединений к gRPC-серверу.
По умолчанию для сокета действуют настройки операционной системы.
Если указано значение “<literal>on</literal>”, то
для сокета включается параметр <c-def>SO_KEEPALIVE</c-def>.
</para>

</directive>


<directive name="grpc_ssl_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

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

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

</directive>


<directive name="grpc_ssl_certificate_key">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

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

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

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

</directive>


<directive name="grpc_ssl_ciphers">
<syntax><value>шифры</value></syntax>
<default>DEFAULT</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

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

</directive>


<directive name="grpc_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
при установлении соединения с gRPC SSL-сервером.
<note>
Директива поддерживается при использовании OpenSSL 1.0.2 и выше.
</note>
</para>

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

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

</directive>


<directive name="grpc_ssl_crl">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="grpc_ssl_name">
<syntax><value>имя</value></syntax>
<default>имя хоста из grpc_pass</default>
<context>http</context>
<context>server</context>
<context>location</context>

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

<para>
По умолчанию используется имя хоста из <link id="grpc_pass"/>.
</para>

</directive>


<directive name="grpc_ssl_password_file">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


<directive name="grpc_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>

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

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

</directive>


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

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

</directive>


<directive name="grpc_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-сессии при
работе с gRPC-сервером.
Если в логах появляются ошибки
“<literal>SSL3_GET_FINISHED:digest check failed</literal>”,
то можно попробовать выключить
повторное использование сессий.
</para>

</directive>


<directive name="grpc_ssl_trusted_certificate">
<syntax><value>файл</value></syntax>
<default/>
<context>http</context>
<context>server</context>
<context>location</context>

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

</directive>


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

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

</directive>


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

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

</directive>

</section>

</module>