Mercurial > hg > nginx-site
diff xml/ru/docs/http/ngx_http_grpc_module.xml @ 2114:b7dd3e8ee9c2
Documented the gRPC proxy module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 16 Mar 2018 21:46:19 +0300 |
parents | xml/ru/docs/http/ngx_http_memcached_module.xml@a9a9a052b5bd |
children | ca7568f67dee |
line wrap: on
line diff
copy from xml/ru/docs/http/ngx_http_memcached_module.xml copy to xml/ru/docs/http/ngx_http_grpc_module.xml --- a/xml/ru/docs/http/ngx_http_memcached_module.xml +++ b/xml/ru/docs/http/ngx_http_grpc_module.xml @@ -7,19 +7,18 @@ <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> -<module name="Модуль ngx_http_memcached_module" - link="/ru/docs/http/ngx_http_memcached_module.html" +<module name="Модуль ngx_http_grpc_module" + link="/ru/docs/http/ngx_http_grpc_module.html" lang="ru" - rev="16"> + rev="1"> <section id="summary"> <para> -Модуль <literal>ngx_http_memcached_module</literal> позволяет получать -ответ из сервера memcached. -Ключ задаётся в переменной <var>$memcached_key</var>. -Ответ в memcached должен быть предварительно помещён внешним по отношению -к nginx’у способом. +Модуль <literal>ngx_http_grpc_module</literal> позволяет передавать запросы +gRPC-серверу (1.13.10). +Для работы этого модуля необходим +модуль <link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link>. </para> </section> @@ -30,14 +29,10 @@ <para> <example> server { + listen 9000 http2; + location / { - set $memcached_key "$uri?$args"; - memcached_pass host:11211; - error_page 404 502 504 = @fallback; - } - - location @fallback { - proxy_pass http://backend; + grpc_pass 127.0.0.1:9000; } } </example> @@ -48,50 +43,49 @@ server { <section id="directives" name="Директивы"> -<directive name="memcached_bind"> +<directive name="grpc_bind"> <syntax> <value>адрес</value> - [ <literal>transparent </literal>] | + [<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), -который будет использоваться в исходящих соединениях с сервером memcached. -В значении параметра допустимо использование переменных (1.3.12). -Специальное значение <literal>off</literal> (1.3.12) отменяет действие +Задаёт локальный IP-адрес с необязательным портом, +который будет использоваться в исходящих соединениях с gRPC-сервером. +В значении параметра допустимо использование переменных. +Специальное значение <literal>off</literal> отменяет действие унаследованной с предыдущего уровня конфигурации -директивы <literal>memcached_bind</literal>, позволяя системе +директивы <literal>grpc_bind</literal>, позволяя системе самостоятельно выбирать локальный IP-адрес и порт. </para> -<para id="memcached_bind_transparent"> -Параметр <literal>transparent</literal> (1.11.0) позволяет +<para id="grpc_bind_transparent"> +Параметр <literal>transparent</literal> позволяет задать нелокальный IP-aдрес, который будет использоваться в -исходящих соединениях с сервером memcached, +исходящих соединениях с gRPC-сервером, например, реальный IP-адрес клиента: <example> -memcached_bind $remote_addr transparent; +grpc_bind $remote_addr transparent; </example> Для работы параметра обычно требуется запустить рабочие процессы nginx с привилегиями <link doc="../ngx_core_module.xml" id="user">суперпользователя</link>. -В Linux этого не требуется (1.13.8), так как если +В Linux этого не требуется, так как если указан параметр <literal>transparent</literal>, то рабочие процессы наследуют capability <literal>CAP_NET_RAW</literal> из главного процесса. Также необходимо настроить таблицу маршрутизации ядра -для перехвата сетевого трафика с сервера memcached. +для перехвата сетевого трафика с gRPC-сервера. </para> </directive> -<directive name="memcached_buffer_size"> +<directive name="grpc_buffer_size"> <syntax><value>размер</value></syntax> <default>4k|8k</default> <context>http</context> @@ -100,14 +94,14 @@ memcached_bind $remote_addr transparent; <para> Задаёт <value>размер</value> буфера, в который будет читаться ответ, -получаемый от сервера memcached. +получаемый от gRPC-сервера. Ответ синхронно передаётся клиенту сразу же по мере его поступления. </para> </directive> -<directive name="memcached_connect_timeout"> +<directive name="grpc_connect_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> @@ -115,54 +109,99 @@ memcached_bind $remote_addr transparent; <context>location</context> <para> -Задаёт таймаут для установления соединения с сервером memcached. +Задаёт таймаут для установления соединения с gRPC-сервером. Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд. </para> </directive> -<directive name="memcached_force_ranges"> -<syntax><literal>on</literal> | <literal>off</literal></syntax> -<default>off</default> +<directive name="grpc_hide_header"> +<syntax><value>поле</value></syntax> +<default/> <context>http</context> <context>server</context> <context>location</context> -<appeared-in>1.7.7</appeared-in> <para> -Включает поддержку диапазонов запрашиваемых байт (byte-range) -для кэшированных и некэшированных ответов сервера memcached -вне зависимости от наличия поля <header>Accept-Ranges</header> -в заголовках этих ответов. +По умолчанию +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="memcached_gzip_flag"> -<syntax><value>флаг</value></syntax> -<default></default> +<directive name="grpc_ignore_headers"> +<syntax><value>поле</value> ...</syntax> +<default/> <context>http</context> <context>server</context> <context>location</context> -<appeared-in>1.3.6</appeared-in> + +<para> +Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера. +В директиве можно указать поля <header>X-Accel-Redirect</header> +и <header>X-Accel-Charset</header>. +</para> <para> -Включает проверку указанного <value>флага</value> в ответе -сервера memcached и установку поля “<literal>Content-Encoding</literal>” -заголовка ответа в “<literal>gzip</literal>”, если этот флаг установлен. +Если не запрещено, обработка этих полей заголовка заключается в следующем: +<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="memcached_next_upstream"> +<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_response</literal> | - <literal>not_found</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> @@ -182,11 +221,40 @@ memcached_bind $remote_addr transparent; <tag-desc>произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;</tag-desc> -<tag-name><literal>invalid_response</literal></tag-name> +<tag-name><literal>invalid_header</literal></tag-name> <tag-desc>сервер вернул пустой или неверный ответ;</tag-desc> -<tag-name><literal>not_found</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> @@ -206,71 +274,82 @@ memcached_bind $remote_addr transparent; <link doc="ngx_http_upstream_module.xml" id="max_fails">неудачной попыткой</link> работы с сервером. Случаи <literal>error</literal>, <literal>timeout</literal> и -<literal>invalid_response</literal> +<literal>invalid_header</literal> всегда считаются неудачными попытками, даже если они не указаны в директиве. -Случай <literal>not_found</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="memcached_next_upstream_tries">количеству попыток</link> -и по <link id="memcached_next_upstream_timeout">времени</link>. +<link id="grpc_next_upstream_tries">количеству попыток</link> +и по <link id="grpc_next_upstream_timeout">времени</link>. </para> </directive> -<directive name="memcached_next_upstream_timeout"> +<directive name="grpc_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="memcached_next_upstream">следующему серверу</link>. +<link id="grpc_next_upstream">следующему серверу</link>. Значение <literal>0</literal> отключает это ограничение. </para> </directive> -<directive name="memcached_next_upstream_tries"> +<directive name="grpc_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="memcached_next_upstream">следующему серверу</link>. +<link id="grpc_next_upstream">следующему серверу</link>. Значение <literal>0</literal> отключает это ограничение. </para> </directive> -<directive name="memcached_pass"> +<directive name="grpc_pass"> <syntax><value>адрес</value></syntax> <default/> <context>location</context> <context>if в location</context> <para> -Задаёт адрес сервера memcached. +Задаёт адрес gRPC-сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и порта: <example> -memcached_pass localhost:11211; +grpc_pass localhost:9000; </example> или в виде пути UNIX-сокета: <example> -memcached_pass unix:/tmp/memcached.socket; +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> @@ -284,7 +363,22 @@ memcached_pass unix:/tmp/memcached.socke </directive> -<directive name="memcached_read_timeout"> +<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> @@ -292,17 +386,17 @@ memcached_pass unix:/tmp/memcached.socke <context>location</context> <para> -Задаёт таймаут при чтении ответа сервера memcached. +Задаёт таймаут при чтении ответа gRPC-сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. -Если по истечении этого времени сервер memcached ничего не передаст, +Если по истечении этого времени gRPC-сервер ничего не передаст, соединение закрывается. </para> </directive> -<directive name="memcached_send_timeout"> +<directive name="grpc_send_timeout"> <syntax><value>время</value></syntax> <default>60s</default> <context>http</context> @@ -310,31 +404,254 @@ memcached_pass unix:/tmp/memcached.socke <context>location</context> <para> -Задаёт таймаут при передаче запроса серверу memcached. +Задаёт таймаут при передаче запроса gRPC-серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. -Если по истечении этого времени сервер memcached не примет новых данных, +Если по истечении этого времени 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_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_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_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_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> - -<section id="variables" name="Встроенные переменные"> - -<para> -<list type="tag"> - -<tag-name id="var_memcached_key"><var>$memcached_key</var></tag-name> -<tag-desc> -Задаёт ключ для получения ответа из сервера memcached. -</tag-desc> - -</list> -</para> - -</section> - </module>