Mercurial > hg > nginx-site
view xml/ru/docs/http/ngx_http_grpc_module.xml @ 2444:d58fc33a0830
Improved description of stream keyval types.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Wed, 16 Oct 2019 19:02:24 +0300 |
parents | d765ffffd08c |
children | bdc7cacb164f |
line wrap: on
line source
<?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="2"> <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://tools.ietf.org/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> </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> </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> </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_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</default> <context>http</context> <context>server</context> <context>location</context> <para> Разрешает указанные протоколы для запросов к gRPC SSL-серверу. </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>