Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_grpc_module.xml @ 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 xml/en/docs/http/ngx_http_memcached_module.xml@a9a9a052b5bd
children ca7568f67dee
comparison
equal deleted inserted replaced
2113:180269c4a220 2114:b7dd3e8ee9c2
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Igor Sysoev
5 Copyright (C) Nginx, Inc.
6 -->
7
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
9
10 <module name="Module ngx_http_grpc_module"
11 link="/en/docs/http/ngx_http_grpc_module.html"
12 lang="en"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 The <literal>ngx_http_grpc_module</literal> module allows passing requests
19 to a gRPC server (1.13.10).
20 The module requires the
21 <link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link> module.
22 </para>
23
24 </section>
25
26
27 <section id="example" name="Example Configuration">
28
29 <para>
30 <example>
31 server {
32 listen 9000 http2;
33
34 location / {
35 grpc_pass 127.0.0.1:9000;
36 }
37 }
38 </example>
39 </para>
40
41 </section>
42
43
44 <section id="directives" name="Directives">
45
46 <directive name="grpc_bind">
47 <syntax>
48 <value>address</value>
49 [<literal>transparent </literal>] |
50 <literal>off</literal></syntax>
51 <default/>
52 <context>http</context>
53 <context>server</context>
54 <context>location</context>
55
56 <para>
57 Makes outgoing connections to a gRPC server originate
58 from the specified local IP address with an optional port.
59 Parameter value can contain variables.
60 The special value <literal>off</literal> cancels the effect
61 of the <literal>grpc_bind</literal> directive
62 inherited from the previous configuration level, which allows the
63 system to auto-assign the local IP address and port.
64 </para>
65
66 <para id="grpc_bind_transparent">
67 The <literal>transparent</literal> parameter allows
68 outgoing connections to a gRPC server originate
69 from a non-local IP address,
70 for example, from a real IP address of a client:
71 <example>
72 grpc_bind $remote_addr transparent;
73 </example>
74 In order for this parameter to work,
75 it is usually necessary to run nginx worker processes with the
76 <link doc="../ngx_core_module.xml" id="user">superuser</link> privileges.
77 On Linux it is not required as if
78 the <literal>transparent</literal> parameter is specified, worker processes
79 inherit the <literal>CAP_NET_RAW</literal> capability from the master process.
80 It is also necessary to configure kernel routing table
81 to intercept network traffic from the gRPC server.
82 </para>
83
84 </directive>
85
86
87 <directive name="grpc_buffer_size">
88 <syntax><value>size</value></syntax>
89 <default>4k|8k</default>
90 <context>http</context>
91 <context>server</context>
92 <context>location</context>
93
94 <para>
95 Sets the <value>size</value> of the buffer used for reading the response
96 received from the gRPC server.
97 The response is passed to the client synchronously, as soon as it is received.
98 </para>
99
100 </directive>
101
102
103 <directive name="grpc_connect_timeout">
104 <syntax><value>time</value></syntax>
105 <default>60s</default>
106 <context>http</context>
107 <context>server</context>
108 <context>location</context>
109
110 <para>
111 Defines a timeout for establishing a connection with a gRPC server.
112 It should be noted that this timeout cannot usually exceed 75 seconds.
113 </para>
114
115 </directive>
116
117
118 <directive name="grpc_hide_header">
119 <syntax><value>field</value></syntax>
120 <default/>
121 <context>http</context>
122 <context>server</context>
123 <context>location</context>
124
125 <para>
126 By default,
127 nginx does not pass the header fields <header>Date</header>,
128 <header>Server</header>, and
129 <header>X-Accel-...</header> from the response of a gRPC
130 server to a client.
131 The <literal>grpc_hide_header</literal> directive sets additional fields
132 that will not be passed.
133 If, on the contrary, the passing of fields needs to be permitted,
134 the <link id="grpc_pass_header"/> directive can be used.
135 </para>
136
137 </directive>
138
139
140 <directive name="grpc_ignore_headers">
141 <syntax><value>field</value> ...</syntax>
142 <default/>
143 <context>http</context>
144 <context>server</context>
145 <context>location</context>
146
147 <para>
148 Disables processing of certain response header fields from the gRPC server.
149 The following fields can be ignored: <header>X-Accel-Redirect</header>
150 and <header>X-Accel-Charset</header>.
151 </para>
152
153 <para>
154 If not disabled, processing of these header fields has the following
155 effect:
156 <list type="bullet" compact="no">
157
158 <listitem>
159 <header>X-Accel-Redirect</header> performs an
160 <link doc="ngx_http_core_module.xml" id="internal">internal
161 redirect</link> to the specified URI;
162 </listitem>
163
164 <listitem>
165 <header>X-Accel-Charset</header> sets the desired
166 <link doc="ngx_http_charset_module.xml" id="charset"/>
167 of a response.
168 </listitem>
169
170 </list>
171 </para>
172
173 </directive>
174
175
176 <directive name="grpc_intercept_errors">
177 <syntax><literal>on</literal> | <literal>off</literal></syntax>
178 <default>off</default>
179 <context>http</context>
180 <context>server</context>
181 <context>location</context>
182
183 <para>
184 Determines whether gRPC server responses with codes greater than or equal
185 to 300 should be passed to a client
186 or be intercepted and redirected to nginx for processing
187 with the <link doc="ngx_http_core_module.xml" id="error_page"/> directive.
188 </para>
189
190 </directive>
191
192
193 <directive name="grpc_next_upstream">
194 <syntax>
195 <literal>error</literal> |
196 <literal>timeout</literal> |
197 <literal>invalid_header</literal> |
198 <literal>http_500</literal> |
199 <literal>http_502</literal> |
200 <literal>http_503</literal> |
201 <literal>http_504</literal> |
202 <literal>http_403</literal> |
203 <literal>http_404</literal> |
204 <literal>http_429</literal> |
205 <literal>non_idempotent</literal> |
206 <literal>off</literal>
207 ...</syntax>
208 <default>error timeout</default>
209 <context>http</context>
210 <context>server</context>
211 <context>location</context>
212
213 <para>
214 Specifies in which cases a request should be passed to the next server:
215 <list type="tag">
216
217 <tag-name><literal>error</literal></tag-name>
218 <tag-desc>an error occurred while establishing a connection with the
219 server, passing a request to it, or reading the response header;</tag-desc>
220
221 <tag-name><literal>timeout</literal></tag-name>
222 <tag-desc>a timeout has occurred while establishing a connection with the
223 server, passing a request to it, or reading the response header;</tag-desc>
224
225 <tag-name><literal>invalid_header</literal></tag-name>
226 <tag-desc>a server returned an empty or invalid response;</tag-desc>
227
228 <tag-name><literal>http_500</literal></tag-name>
229 <tag-desc>a server returned a response with the code 500;</tag-desc>
230
231 <tag-name><literal>http_502</literal></tag-name>
232 <tag-desc>a server returned a response with the code 502;</tag-desc>
233
234 <tag-name><literal>http_503</literal></tag-name>
235 <tag-desc>a server returned a response with the code 503;</tag-desc>
236
237 <tag-name><literal>http_504</literal></tag-name>
238 <tag-desc>a server returned a response with the code 504;</tag-desc>
239
240 <tag-name><literal>http_403</literal></tag-name>
241 <tag-desc>a server returned a response with the code 403;</tag-desc>
242
243 <tag-name><literal>http_404</literal></tag-name>
244 <tag-desc>a server returned a response with the code 404;</tag-desc>
245
246 <tag-name><literal>http_429</literal></tag-name>
247 <tag-desc>a server returned a response with the code 429;</tag-desc>
248
249 <tag-name id="non_idempotent"><literal>non_idempotent</literal></tag-name>
250 <tag-desc>normally, requests with a
251 <link url="https://tools.ietf.org/html/rfc7231#section-4.2.2">non-idempotent</link>
252 method
253 (<literal>POST</literal>, <literal>LOCK</literal>, <literal>PATCH</literal>)
254 are not passed to the next server
255 if a request has been sent to an upstream server;
256 enabling this option explicitly allows retrying such requests;
257 </tag-desc>
258
259 <tag-name><literal>off</literal></tag-name>
260 <tag-desc>disables passing a request to the next server.</tag-desc>
261
262 </list>
263 </para>
264
265 <para>
266 One should bear in mind that passing a request to the next server is
267 only possible if nothing has been sent to a client yet.
268 That is, if an error or timeout occurs in the middle of the
269 transferring of a response, fixing this is impossible.
270 </para>
271
272 <para>
273 The directive also defines what is considered an
274 <link doc="ngx_http_upstream_module.xml" id="max_fails">unsuccessful
275 attempt</link> of communication with a server.
276 The cases of <literal>error</literal>, <literal>timeout</literal> and
277 <literal>invalid_header</literal> are always considered unsuccessful attempts,
278 even if they are not specified in the directive.
279 The cases of <literal>http_500</literal>, <literal>http_502</literal>,
280 <literal>http_503</literal>, <literal>http_504</literal>,
281 and <literal>http_429</literal> are
282 considered unsuccessful attempts only if they are specified in the directive.
283 The cases of <literal>http_403</literal> and <literal>http_404</literal>
284 are never considered unsuccessful attempts.
285 </para>
286
287 <para>
288 Passing a request to the next server can be limited by
289 <link id="grpc_next_upstream_tries">the number of tries</link>
290 and by <link id="grpc_next_upstream_timeout">time</link>.
291 </para>
292
293 </directive>
294
295
296 <directive name="grpc_next_upstream_timeout">
297 <syntax><value>time</value></syntax>
298 <default>0</default>
299 <context>http</context>
300 <context>server</context>
301 <context>location</context>
302
303 <para>
304 Limits the time during which a request can be passed to the
305 <link id="grpc_next_upstream">next server</link>.
306 The <literal>0</literal> value turns off this limitation.
307 </para>
308
309 </directive>
310
311
312 <directive name="grpc_next_upstream_tries">
313 <syntax><value>number</value></syntax>
314 <default>0</default>
315 <context>http</context>
316 <context>server</context>
317 <context>location</context>
318
319 <para>
320 Limits the number of possible tries for passing a request to the
321 <link id="grpc_next_upstream">next server</link>.
322 The <literal>0</literal> value turns off this limitation.
323 </para>
324
325 </directive>
326
327
328 <directive name="grpc_pass">
329 <syntax><value>address</value></syntax>
330 <default/>
331 <context>location</context>
332 <context>if in location</context>
333
334 <para>
335 Sets the gRPC server address.
336 The address can be specified as a domain name or IP address,
337 and a port:
338 <example>
339 grpc_pass localhost:9000;
340 </example>
341 or as a UNIX-domain socket path:
342 <example>
343 grpc_pass unix:/tmp/grpc.socket;
344 </example>
345 Alternatively, the “<literal>grpc://</literal>” scheme can be used:
346 <example>
347 grpc_pass grpc://127.0.0.1:9000;
348 </example>
349 To use gRPC over SSL, the “<literal>grpcs://</literal>” scheme should be used:
350 <example>
351 grpc_pass grpcs://127.0.0.1:443;
352 </example>
353 </para>
354
355 <para>
356 If a domain name resolves to several addresses, all of them will be
357 used in a round-robin fashion.
358 In addition, an address can be specified as a
359 <link doc="ngx_http_upstream_module.xml">server group</link>.
360 </para>
361
362 </directive>
363
364
365 <directive name="grpc_pass_header">
366 <syntax><value>field</value></syntax>
367 <default/>
368 <context>http</context>
369 <context>server</context>
370 <context>location</context>
371
372 <para>
373 Permits passing <link id="grpc_hide_header">otherwise disabled</link> header
374 fields from a gRPC server to a client.
375 </para>
376
377 </directive>
378
379
380 <directive name="grpc_read_timeout">
381 <syntax><value>time</value></syntax>
382 <default>60s</default>
383 <context>http</context>
384 <context>server</context>
385 <context>location</context>
386
387 <para>
388 Defines a timeout for reading a response from the gRPC server.
389 The timeout is set only between two successive read operations,
390 not for the transmission of the whole response.
391 If the gRPC server does not transmit anything within this time,
392 the connection is closed.
393 </para>
394
395 </directive>
396
397
398 <directive name="grpc_send_timeout">
399 <syntax><value>time</value></syntax>
400 <default>60s</default>
401 <context>http</context>
402 <context>server</context>
403 <context>location</context>
404
405 <para>
406 Sets a timeout for transmitting a request to the gRPC server.
407 The timeout is set only between two successive write operations,
408 not for the transmission of the whole request.
409 If the gRPC server does not receive anything within this time,
410 the connection is closed.
411 </para>
412
413 </directive>
414
415
416 <directive name="grpc_set_header">
417 <syntax><value>field</value> <value>value</value></syntax>
418 <default>Content-Length $content_length</default>
419 <context>http</context>
420 <context>server</context>
421 <context>location</context>
422
423 <para>
424 Allows redefining or appending fields to the request header
425 <link id="grpc_pass_request_headers">passed</link> to the gRPC server.
426 The <value>value</value> can contain text, variables, and their combinations.
427 These directives are inherited from the previous level if and
428 only if there are no
429 <literal>grpc_set_header</literal>
430 directives defined on the current level.
431 </para>
432
433 <para>
434 If the value of a header field is an empty string then this
435 field will not be passed to a gRPC server:
436 <example>
437 grpc_set_header Accept-Encoding "";
438 </example>
439 </para>
440
441 </directive>
442
443
444 <directive name="grpc_ssl_certificate">
445 <syntax><value>file</value></syntax>
446 <default/>
447 <context>http</context>
448 <context>server</context>
449 <context>location</context>
450
451 <para>
452 Specifies a <value>file</value> with the certificate in the PEM format
453 used for authentication to a gRPC SSL server.
454 </para>
455
456 </directive>
457
458
459 <directive name="grpc_ssl_certificate_key">
460 <syntax><value>file</value></syntax>
461 <default/>
462 <context>http</context>
463 <context>server</context>
464 <context>location</context>
465
466 <para>
467 Specifies a <value>file</value> with the secret key in the PEM format
468 used for authentication to a gRPC SSL server.
469 </para>
470
471 <para>
472 The value
473 <literal>engine</literal>:<value>name</value>:<value>id</value>
474 can be specified instead of the <value>file</value>,
475 which loads a secret key with a specified <value>id</value>
476 from the OpenSSL engine <value>name</value>.
477 </para>
478
479 </directive>
480
481
482 <directive name="grpc_ssl_ciphers">
483 <syntax><value>ciphers</value></syntax>
484 <default>DEFAULT</default>
485 <context>http</context>
486 <context>server</context>
487 <context>location</context>
488
489 <para>
490 Specifies the enabled ciphers for requests to a gRPC SSL server.
491 The ciphers are specified in the format understood by the OpenSSL library.
492 </para>
493
494 <para>
495 The full list can be viewed using the
496 “<command>openssl ciphers</command>” command.
497 </para>
498
499 </directive>
500
501
502 <directive name="grpc_ssl_crl">
503 <syntax><value>file</value></syntax>
504 <default/>
505 <context>http</context>
506 <context>server</context>
507 <context>location</context>
508
509 <para>
510 Specifies a <value>file</value> with revoked certificates (CRL)
511 in the PEM format used to <link id="grpc_ssl_verify">verify</link>
512 the certificate of the gRPC SSL server.
513 </para>
514
515 </directive>
516
517
518 <directive name="grpc_ssl_name">
519 <syntax><value>name</value></syntax>
520 <default>host from grpc_pass</default>
521 <context>http</context>
522 <context>server</context>
523 <context>location</context>
524
525 <para>
526 Allows overriding the server name used to
527 <link id="grpc_ssl_verify">verify</link>
528 the certificate of the gRPC SSL server and to be
529 <link id="grpc_ssl_server_name">passed through SNI</link>
530 when establishing a connection with the gRPC SSL server.
531 </para>
532
533 <para>
534 By default, the host part from <link id="grpc_pass"/> is used.
535 </para>
536
537 </directive>
538
539
540 <directive name="grpc_ssl_password_file">
541 <syntax><value>file</value></syntax>
542 <default/>
543 <context>http</context>
544 <context>server</context>
545 <context>location</context>
546
547 <para>
548 Specifies a <value>file</value> with passphrases for
549 <link id="grpc_ssl_certificate_key">secret keys</link>
550 where each passphrase is specified on a separate line.
551 Passphrases are tried in turn when loading the key.
552 </para>
553
554 </directive>
555
556
557 <directive name="grpc_ssl_server_name">
558 <syntax><literal>on</literal> | <literal>off</literal></syntax>
559 <default>off</default>
560 <context>http</context>
561 <context>server</context>
562 <context>location</context>
563
564 <para>
565 Enables or disables passing of the server name through
566 <link url="http://en.wikipedia.org/wiki/Server_Name_Indication">TLS
567 Server Name Indication extension</link> (SNI, RFC 6066)
568 when establishing a connection with the gRPC SSL server.
569 </para>
570
571 </directive>
572
573
574 <directive name="grpc_ssl_session_reuse">
575 <syntax><literal>on</literal> | <literal>off</literal></syntax>
576 <default>on</default>
577 <context>http</context>
578 <context>server</context>
579 <context>location</context>
580
581 <para>
582 Determines whether SSL sessions can be reused when working with
583 the gRPC server.
584 If the errors
585 “<literal>SSL3_GET_FINISHED:digest check failed</literal>”
586 appear in the logs, try disabling session reuse.
587 </para>
588
589 </directive>
590
591
592 <directive name="grpc_ssl_protocols">
593 <syntax>
594 [<literal>SSLv2</literal>]
595 [<literal>SSLv3</literal>]
596 [<literal>TLSv1</literal>]
597 [<literal>TLSv1.1</literal>]
598 [<literal>TLSv1.2</literal>]
599 [<literal>TLSv1.3</literal>]</syntax>
600 <default>TLSv1 TLSv1.1 TLSv1.2</default>
601 <context>http</context>
602 <context>server</context>
603 <context>location</context>
604
605 <para>
606 Enables the specified protocols for requests to a gRPC SSL server.
607 </para>
608
609 </directive>
610
611
612 <directive name="grpc_ssl_trusted_certificate">
613 <syntax><value>file</value></syntax>
614 <default/>
615 <context>http</context>
616 <context>server</context>
617 <context>location</context>
618
619 <para>
620 Specifies a <value>file</value> with trusted CA certificates in the PEM format
621 used to <link id="grpc_ssl_verify">verify</link>
622 the certificate of the gRPC SSL server.
623 </para>
624
625 </directive>
626
627
628 <directive name="grpc_ssl_verify">
629 <syntax><literal>on</literal> | <literal>off</literal></syntax>
630 <default>off</default>
631 <context>http</context>
632 <context>server</context>
633 <context>location</context>
634
635 <para>
636 Enables or disables verification of the gRPC SSL server certificate.
637 </para>
638
639 </directive>
640
641
642 <directive name="grpc_ssl_verify_depth">
643 <syntax><value>number</value></syntax>
644 <default>1</default>
645 <context>http</context>
646 <context>server</context>
647 <context>location</context>
648
649 <para>
650 Sets the verification depth in the gRPC SSL server certificates chain.
651 </para>
652
653 </directive>
654
655 </section>
656
657 </module>