Mercurial > hg > nginx-site
changeset 2114:b7dd3e8ee9c2
Documented the gRPC proxy module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 16 Mar 2018 21:46:19 +0300 |
parents | 180269c4a220 |
children | d7d65cc0aa1e |
files | xml/en/GNUmakefile xml/en/docs/http/ngx_http_grpc_module.xml xml/en/docs/index.xml xml/ru/GNUmakefile xml/ru/docs/http/ngx_http_grpc_module.xml xml/ru/docs/index.xml |
diffstat | 6 files changed, 1328 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/GNUmakefile Thu Mar 15 21:24:00 2018 +0300 +++ b/xml/en/GNUmakefile Fri Mar 16 21:46:19 2018 +0300 @@ -54,6 +54,7 @@ http/ngx_http_flv_module \ http/ngx_http_geo_module \ http/ngx_http_geoip_module \ + http/ngx_http_grpc_module \ http/ngx_http_gunzip_module \ http/ngx_http_gzip_module \ http/ngx_http_gzip_static_module \
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/en/docs/http/ngx_http_grpc_module.xml Fri Mar 16 21:46:19 2018 +0300 @@ -0,0 +1,657 @@ +<?xml version="1.0"?> + +<!-- + Copyright (C) Igor Sysoev + Copyright (C) Nginx, Inc. + --> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Module ngx_http_grpc_module" + link="/en/docs/http/ngx_http_grpc_module.html" + lang="en" + rev="1"> + +<section id="summary"> + +<para> +The <literal>ngx_http_grpc_module</literal> module allows passing requests +to a gRPC server (1.13.10). +The module requires the +<link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link> module. +</para> + +</section> + + +<section id="example" name="Example Configuration"> + +<para> +<example> +server { + listen 9000 http2; + + location / { + grpc_pass 127.0.0.1:9000; + } +} +</example> +</para> + +</section> + + +<section id="directives" name="Directives"> + +<directive name="grpc_bind"> +<syntax> + <value>address</value> + [<literal>transparent </literal>] | + <literal>off</literal></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Makes outgoing connections to a gRPC server originate +from the specified local IP address with an optional port. +Parameter value can contain variables. +The special value <literal>off</literal> cancels the effect +of the <literal>grpc_bind</literal> directive +inherited from the previous configuration level, which allows the +system to auto-assign the local IP address and port. +</para> + +<para id="grpc_bind_transparent"> +The <literal>transparent</literal> parameter allows +outgoing connections to a gRPC server originate +from a non-local IP address, +for example, from a real IP address of a client: +<example> +grpc_bind $remote_addr transparent; +</example> +In order for this parameter to work, +it is usually necessary to run nginx worker processes with the +<link doc="../ngx_core_module.xml" id="user">superuser</link> privileges. +On Linux it is not required as if +the <literal>transparent</literal> parameter is specified, worker processes +inherit the <literal>CAP_NET_RAW</literal> capability from the master process. +It is also necessary to configure kernel routing table +to intercept network traffic from the gRPC server. +</para> + +</directive> + + +<directive name="grpc_buffer_size"> +<syntax><value>size</value></syntax> +<default>4k|8k</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the <value>size</value> of the buffer used for reading the response +received from the gRPC server. +The response is passed to the client synchronously, as soon as it is received. +</para> + +</directive> + + +<directive name="grpc_connect_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a timeout for establishing a connection with a gRPC server. +It should be noted that this timeout cannot usually exceed 75 seconds. +</para> + +</directive> + + +<directive name="grpc_hide_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +By default, +nginx does not pass the header fields <header>Date</header>, +<header>Server</header>, and +<header>X-Accel-...</header> from the response of a gRPC +server to a client. +The <literal>grpc_hide_header</literal> directive sets additional fields +that will not be passed. +If, on the contrary, the passing of fields needs to be permitted, +the <link id="grpc_pass_header"/> directive can be used. +</para> + +</directive> + + +<directive name="grpc_ignore_headers"> +<syntax><value>field</value> ...</syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Disables processing of certain response header fields from the gRPC server. +The following fields can be ignored: <header>X-Accel-Redirect</header> +and <header>X-Accel-Charset</header>. +</para> + +<para> +If not disabled, processing of these header fields has the following +effect: +<list type="bullet" compact="no"> + +<listitem> +<header>X-Accel-Redirect</header> performs an +<link doc="ngx_http_core_module.xml" id="internal">internal +redirect</link> to the specified URI; +</listitem> + +<listitem> +<header>X-Accel-Charset</header> sets the desired +<link doc="ngx_http_charset_module.xml" id="charset"/> +of a response. +</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> +Determines whether gRPC server responses with codes greater than or equal +to 300 should be passed to a client +or be intercepted and redirected to nginx for processing +with the <link doc="ngx_http_core_module.xml" id="error_page"/> directive. +</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> +Specifies in which cases a request should be passed to the next server: +<list type="tag"> + +<tag-name><literal>error</literal></tag-name> +<tag-desc>an error occurred while establishing a connection with the +server, passing a request to it, or reading the response header;</tag-desc> + +<tag-name><literal>timeout</literal></tag-name> +<tag-desc>a timeout has occurred while establishing a connection with the +server, passing a request to it, or reading the response header;</tag-desc> + +<tag-name><literal>invalid_header</literal></tag-name> +<tag-desc>a server returned an empty or invalid response;</tag-desc> + +<tag-name><literal>http_500</literal></tag-name> +<tag-desc>a server returned a response with the code 500;</tag-desc> + +<tag-name><literal>http_502</literal></tag-name> +<tag-desc>a server returned a response with the code 502;</tag-desc> + +<tag-name><literal>http_503</literal></tag-name> +<tag-desc>a server returned a response with the code 503;</tag-desc> + +<tag-name><literal>http_504</literal></tag-name> +<tag-desc>a server returned a response with the code 504;</tag-desc> + +<tag-name><literal>http_403</literal></tag-name> +<tag-desc>a server returned a response with the code 403;</tag-desc> + +<tag-name><literal>http_404</literal></tag-name> +<tag-desc>a server returned a response with the code 404;</tag-desc> + +<tag-name><literal>http_429</literal></tag-name> +<tag-desc>a server returned a response with the code 429;</tag-desc> + +<tag-name id="non_idempotent"><literal>non_idempotent</literal></tag-name> +<tag-desc>normally, requests with a +<link url="https://tools.ietf.org/html/rfc7231#section-4.2.2">non-idempotent</link> +method +(<literal>POST</literal>, <literal>LOCK</literal>, <literal>PATCH</literal>) +are not passed to the next server +if a request has been sent to an upstream server; +enabling this option explicitly allows retrying such requests; +</tag-desc> + +<tag-name><literal>off</literal></tag-name> +<tag-desc>disables passing a request to the next server.</tag-desc> + +</list> +</para> + +<para> +One should bear in mind that passing a request to the next server is +only possible if nothing has been sent to a client yet. +That is, if an error or timeout occurs in the middle of the +transferring of a response, fixing this is impossible. +</para> + +<para> +The directive also defines what is considered an +<link doc="ngx_http_upstream_module.xml" id="max_fails">unsuccessful +attempt</link> of communication with a server. +The cases of <literal>error</literal>, <literal>timeout</literal> and +<literal>invalid_header</literal> are always considered unsuccessful attempts, +even if they are not specified in the directive. +The cases of <literal>http_500</literal>, <literal>http_502</literal>, +<literal>http_503</literal>, <literal>http_504</literal>, +and <literal>http_429</literal> are +considered unsuccessful attempts only if they are specified in the directive. +The cases of <literal>http_403</literal> and <literal>http_404</literal> +are never considered unsuccessful attempts. +</para> + +<para> +Passing a request to the next server can be limited by +<link id="grpc_next_upstream_tries">the number of tries</link> +and by <link id="grpc_next_upstream_timeout">time</link>. +</para> + +</directive> + + +<directive name="grpc_next_upstream_timeout"> +<syntax><value>time</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Limits the time during which a request can be passed to the +<link id="grpc_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + +<directive name="grpc_next_upstream_tries"> +<syntax><value>number</value></syntax> +<default>0</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Limits the number of possible tries for passing a request to the +<link id="grpc_next_upstream">next server</link>. +The <literal>0</literal> value turns off this limitation. +</para> + +</directive> + + +<directive name="grpc_pass"> +<syntax><value>address</value></syntax> +<default/> +<context>location</context> +<context>if in location</context> + +<para> +Sets the gRPC server address. +The address can be specified as a domain name or IP address, +and a port: +<example> +grpc_pass localhost:9000; +</example> +or as a UNIX-domain socket path: +<example> +grpc_pass unix:/tmp/grpc.socket; +</example> +Alternatively, the “<literal>grpc://</literal>” scheme can be used: +<example> +grpc_pass grpc://127.0.0.1:9000; +</example> +To use gRPC over SSL, the “<literal>grpcs://</literal>” scheme should be used: +<example> +grpc_pass grpcs://127.0.0.1:443; +</example> +</para> + +<para> +If a domain name resolves to several addresses, all of them will be +used in a round-robin fashion. +In addition, an address can be specified as a +<link doc="ngx_http_upstream_module.xml">server group</link>. +</para> + +</directive> + + +<directive name="grpc_pass_header"> +<syntax><value>field</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Permits passing <link id="grpc_hide_header">otherwise disabled</link> header +fields from a gRPC server to a client. +</para> + +</directive> + + +<directive name="grpc_read_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Defines a timeout for reading a response from the gRPC server. +The timeout is set only between two successive read operations, +not for the transmission of the whole response. +If the gRPC server does not transmit anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="grpc_send_timeout"> +<syntax><value>time</value></syntax> +<default>60s</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets a timeout for transmitting a request to the gRPC server. +The timeout is set only between two successive write operations, +not for the transmission of the whole request. +If the gRPC server does not receive anything within this time, +the connection is closed. +</para> + +</directive> + + +<directive name="grpc_set_header"> +<syntax><value>field</value> <value>value</value></syntax> +<default>Content-Length $content_length</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Allows redefining or appending fields to the request header +<link id="grpc_pass_request_headers">passed</link> to the gRPC server. +The <value>value</value> can contain text, variables, and their combinations. +These directives are inherited from the previous level if and +only if there are no +<literal>grpc_set_header</literal> +directives defined on the current level. +</para> + +<para> +If the value of a header field is an empty string then this +field will not be passed to a gRPC server: +<example> +grpc_set_header Accept-Encoding ""; +</example> +</para> + +</directive> + + +<directive name="grpc_ssl_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a <value>file</value> with the certificate in the PEM format +used for authentication to a gRPC SSL server. +</para> + +</directive> + + +<directive name="grpc_ssl_certificate_key"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a <value>file</value> with the secret key in the PEM format +used for authentication to a gRPC SSL server. +</para> + +<para> +The value +<literal>engine</literal>:<value>name</value>:<value>id</value> +can be specified instead of the <value>file</value>, +which loads a secret key with a specified <value>id</value> +from the OpenSSL engine <value>name</value>. +</para> + +</directive> + + +<directive name="grpc_ssl_ciphers"> +<syntax><value>ciphers</value></syntax> +<default>DEFAULT</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies the enabled ciphers for requests to a gRPC SSL server. +The ciphers are specified in the format understood by the OpenSSL library. +</para> + +<para> +The full list can be viewed using the +“<command>openssl ciphers</command>” command. +</para> + +</directive> + + +<directive name="grpc_ssl_crl"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a <value>file</value> with revoked certificates (CRL) +in the PEM format used to <link id="grpc_ssl_verify">verify</link> +the certificate of the gRPC SSL server. +</para> + +</directive> + + +<directive name="grpc_ssl_name"> +<syntax><value>name</value></syntax> +<default>host from grpc_pass</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Allows overriding the server name used to +<link id="grpc_ssl_verify">verify</link> +the certificate of the gRPC SSL server and to be +<link id="grpc_ssl_server_name">passed through SNI</link> +when establishing a connection with the gRPC SSL server. +</para> + +<para> +By default, the host part from <link id="grpc_pass"/> is used. +</para> + +</directive> + + +<directive name="grpc_ssl_password_file"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a <value>file</value> with passphrases for +<link id="grpc_ssl_certificate_key">secret keys</link> +where each passphrase is specified on a separate line. +Passphrases are tried in turn when loading the key. +</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> +Enables or disables passing of the server name through +<link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS +Server Name Indication extension</link> (SNI, RFC 6066) +when establishing a connection with the gRPC SSL server. +</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> +Determines whether SSL sessions can be reused when working with +the gRPC server. +If the errors +“<literal>SSL3_GET_FINISHED:digest check failed</literal>” +appear in the logs, try disabling session reuse. +</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> +Enables the specified protocols for requests to a gRPC SSL server. +</para> + +</directive> + + +<directive name="grpc_ssl_trusted_certificate"> +<syntax><value>file</value></syntax> +<default/> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Specifies a <value>file</value> with trusted CA certificates in the PEM format +used to <link id="grpc_ssl_verify">verify</link> +the certificate of the gRPC SSL server. +</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> +Enables or disables verification of the gRPC SSL server certificate. +</para> + +</directive> + + +<directive name="grpc_ssl_verify_depth"> +<syntax><value>number</value></syntax> +<default>1</default> +<context>http</context> +<context>server</context> +<context>location</context> + +<para> +Sets the verification depth in the gRPC SSL server certificates chain. +</para> + +</directive> + +</section> + +</module>
--- a/xml/en/docs/index.xml Thu Mar 15 21:24:00 2018 +0300 +++ b/xml/en/docs/index.xml Fri Mar 16 21:46:19 2018 +0300 @@ -8,7 +8,7 @@ <article name="nginx documentation" link="/en/docs/" lang="en" - rev="43" + rev="44" toc="no"> @@ -285,6 +285,11 @@ </listitem> <listitem> +<link doc="http/ngx_http_grpc_module.xml"> +ngx_http_grpc_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_gunzip_module.xml"> ngx_http_gunzip_module</link> </listitem>
--- a/xml/ru/GNUmakefile Thu Mar 15 21:24:00 2018 +0300 +++ b/xml/ru/GNUmakefile Fri Mar 16 21:46:19 2018 +0300 @@ -42,6 +42,7 @@ http/ngx_http_flv_module \ http/ngx_http_geo_module \ http/ngx_http_geoip_module \ + http/ngx_http_grpc_module \ http/ngx_http_gunzip_module \ http/ngx_http_gzip_module \ http/ngx_http_gzip_static_module \
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_grpc_module.xml Fri Mar 16 21:46:19 2018 +0300 @@ -0,0 +1,657 @@ +<?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="1"> + +<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_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> + +</module>
--- a/xml/ru/docs/index.xml Thu Mar 15 21:24:00 2018 +0300 +++ b/xml/ru/docs/index.xml Fri Mar 16 21:46:19 2018 +0300 @@ -8,7 +8,7 @@ <article name="nginx: документация" link="/ru/docs/" lang="ru" - rev="43" + rev="44" toc="no"> @@ -290,6 +290,11 @@ </listitem> <listitem> +<link doc="http/ngx_http_grpc_module.xml"> +ngx_http_grpc_module</link> +</listitem> + +<listitem> <link doc="http/ngx_http_gunzip_module.xml"> ngx_http_gunzip_module</link> </listitem>