Mercurial > hg > nginx-site

changeset 2114:b7dd3e8ee9c2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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, 831 insertions(+), 184 deletions(-) [+]
line wrap: on
line diff
--- a/xml/en/GNUmakefile
+++ b/xml/en/GNUmakefile
@@ -54,6 +54,7 @@ REFS =									\
 		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			\
copy from xml/en/docs/http/ngx_http_memcached_module.xml
copy to xml/en/docs/http/ngx_http_grpc_module.xml
--- a/xml/en/docs/http/ngx_http_memcached_module.xml
+++ b/xml/en/docs/http/ngx_http_grpc_module.xml
@@ -7,19 +7,18 @@
 
 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
 
-<module name="Module ngx_http_memcached_module"
-        link="/en/docs/http/ngx_http_memcached_module.html"
+<module name="Module ngx_http_grpc_module"
+        link="/en/docs/http/ngx_http_grpc_module.html"
         lang="en"
-        rev="16">
+        rev="1">
 
 <section id="summary">
 
 <para>
-The <literal>ngx_http_memcached_module</literal> module is used to obtain
-responses from a memcached server.
-The key is set in the <var>$memcached_key</var> variable.
-A response should be put in memcached in advance by means
-external to nginx.
+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>
@@ -30,14 +29,10 @@ external to nginx.
 <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,49 +43,48 @@ server {
 
 <section id="directives" name="Directives">
 
-<directive name="memcached_bind">
+<directive name="grpc_bind">
 <syntax>
     <value>address</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>
-Makes outgoing connections to a memcached server originate
-from the specified local IP address with an optional port (1.11.2).
-Parameter value can contain variables (1.3.12).
-The special value <literal>off</literal> (1.3.12) cancels the effect
-of the <literal>memcached_bind</literal> directive
+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="memcached_bind_transparent">
-The <literal>transparent</literal> parameter (1.11.0) allows
-outgoing connections to a memcached server originate
+<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>
-memcached_bind $remote_addr transparent;
+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 (1.13.8) as if
+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 memcached server.
+to intercept network traffic from the gRPC server.
 </para>
 
 </directive>
 
 
-<directive name="memcached_buffer_size">
+<directive name="grpc_buffer_size">
 <syntax><value>size</value></syntax>
 <default>4k|8k</default>
 <context>http</context>
@@ -99,14 +93,14 @@ to intercept network traffic from the me
 
 <para>
 Sets the <value>size</value> of the buffer used for reading the response
-received from the memcached server.
+received from the gRPC server.
 The response is passed to the client synchronously, as soon as it is received.
 </para>
 
 </directive>
 
 
-<directive name="memcached_connect_timeout">
+<directive name="grpc_connect_timeout">
 <syntax><value>time</value></syntax>
 <default>60s</default>
 <context>http</context>
@@ -114,54 +108,101 @@ The response is passed to the client syn
 <context>location</context>
 
 <para>
-Defines a timeout for establishing a connection with a memcached server.
+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="memcached_force_ranges">
-<syntax><literal>on</literal> | <literal>off</literal></syntax>
-<default>off</default>
+<directive name="grpc_hide_header">
+<syntax><value>field</value></syntax>
+<default/>
 <context>http</context>
 <context>server</context>
 <context>location</context>
-<appeared-in>1.7.7</appeared-in>
 
 <para>
-Enables byte-range support
-for both cached and uncached responses from the memcached server
-regardless of the <header>Accept-Ranges</header> field in these responses.
+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="memcached_gzip_flag">
-<syntax><value>flag</value></syntax>
-<default></default>
+<directive name="grpc_ignore_headers">
+<syntax><value>field</value> ...</syntax>
+<default/>
 <context>http</context>
 <context>server</context>
 <context>location</context>
-<appeared-in>1.3.6</appeared-in>
+
+<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>
-Enables the test for the <value>flag</value> presence in the memcached
-server response and sets the “<literal>Content-Encoding</literal>”
-response header field to “<literal>gzip</literal>”
-if the flag is set.
+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="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>
+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_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>
@@ -181,11 +222,39 @@ server, passing a request to it, or read
 <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_response</literal></tag-name>
+<tag-name><literal>invalid_header</literal></tag-name>
 <tag-desc>a server returned an empty or invalid response;</tag-desc>
 
-<tag-name><literal>not_found</literal></tag-name>
-<tag-desc>a response was not found on the server;</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>
@@ -205,71 +274,81 @@ The directive also defines what is consi
 <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_response</literal> are always considered unsuccessful attempts,
+<literal>invalid_header</literal> are always considered unsuccessful attempts,
 even if they are not specified in the directive.
-The case of <literal>not_found</literal>
-is never considered an unsuccessful attempt.
+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="memcached_next_upstream_tries">the number of tries</link>
-and by <link id="memcached_next_upstream_timeout">time</link>.
+<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="memcached_next_upstream_timeout">
+<directive name="grpc_next_upstream_timeout">
 <syntax><value>time</value></syntax>
 <default>0</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
-<appeared-in>1.7.5</appeared-in>
 
 <para>
 Limits the time during which a request can be passed to the
-<link id="memcached_next_upstream">next server</link>.
+<link id="grpc_next_upstream">next server</link>.
 The <literal>0</literal> value turns off this limitation.
 </para>
 
 </directive>
 
 
-<directive name="memcached_next_upstream_tries">
+<directive name="grpc_next_upstream_tries">
 <syntax><value>number</value></syntax>
 <default>0</default>
 <context>http</context>
 <context>server</context>
 <context>location</context>
-<appeared-in>1.7.5</appeared-in>
 
 <para>
 Limits the number of possible tries for passing a request to the
-<link id="memcached_next_upstream">next server</link>.
+<link id="grpc_next_upstream">next server</link>.
 The <literal>0</literal> value turns off this limitation.
 </para>
 
 </directive>
 
 
-<directive name="memcached_pass">
+<directive name="grpc_pass">
 <syntax><value>address</value></syntax>
 <default/>
 <context>location</context>
 <context>if in location</context>
 
 <para>
-Sets the memcached server address.
+Sets the gRPC server address.
 The address can be specified as a domain name or IP address,
 and a port:
 <example>
-memcached_pass localhost:11211;
+grpc_pass localhost:9000;
 </example>
 or as a UNIX-domain socket path:
 <example>
-memcached_pass unix:/tmp/memcached.socket;
+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>
 
@@ -283,7 +362,22 @@ In addition, an address can be specified
 </directive>
 
 
-<directive name="memcached_read_timeout">
+<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>
@@ -291,17 +385,17 @@ In addition, an address can be specified
 <context>location</context>
 
 <para>
-Defines a timeout for reading a response from the memcached server.
+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 memcached server does not transmit anything within this time,
+If the gRPC server does not transmit anything within this time,
 the connection is closed.
 </para>
 
 </directive>
 
 
-<directive name="memcached_send_timeout">
+<directive name="grpc_send_timeout">
 <syntax><value>time</value></syntax>
 <default>60s</default>
 <context>http</context>
@@ -309,31 +403,255 @@ the connection is closed.
 <context>location</context>
 
 <para>
-Sets a timeout for transmitting a request to the memcached server.
+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 memcached server does not receive anything within this time,
+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>
 
-
-<section id="variables" name="Embedded Variables">
-
-<para>
-<list type="tag">
-
-<tag-name id="var_memcached_key"><var>$memcached_key</var></tag-name>
-<tag-desc>
-Defines a key for obtaining response from a memcached server.
-</tag-desc>
-
-</list>
-</para>
-
-</section>
-
 </module>
--- a/xml/en/docs/index.xml
+++ b/xml/en/docs/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx documentation"
          link="/en/docs/"
          lang="en"
-         rev="43"
+         rev="44"
          toc="no">
 
 
@@ -285,6 +285,11 @@ ngx_http_geoip_module</link>
 </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
+++ b/xml/ru/GNUmakefile
@@ -42,6 +42,7 @@ REFS =									\
 		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			\
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>
--- a/xml/ru/docs/index.xml
+++ b/xml/ru/docs/index.xml
@@ -8,7 +8,7 @@
 <article name="nginx: документация"
          link="/ru/docs/"
          lang="ru"
-         rev="43"
+         rev="44"
          toc="no">
 
 
@@ -290,6 +290,11 @@ ngx_http_geoip_module</link>
 </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>