Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_grpc_module.xml @ 2114:b7dd3e8ee9c2
Documented the gRPC proxy module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 16 Mar 2018 21:46:19 +0300 |
parents | xml/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> |