Mercurial > hg > nginx-site

comparison xml/ru/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/ru/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="Модуль ngx_http_grpc_module"
11 link="/ru/docs/http/ngx_http_grpc_module.html"
12 lang="ru"
13 rev="1">
14
15 <section id="summary">
16
17 <para>
18 Модуль <literal>ngx_http_grpc_module</literal> позволяет передавать запросы
19 gRPC-серверу (1.13.10).
20 Для работы этого модуля необходим
21 модуль <link doc="ngx_http_v2_module.xml">ngx_http_v2_module</link>.
22 </para>
23
24 </section>
25
26
27 <section id="example" name="Пример конфигурации">
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="Директивы">
45
46 <directive name="grpc_bind">
47 <syntax>
48 <value>адрес</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 Задаёт локальный IP-адрес с необязательным портом,
58 который будет использоваться в исходящих соединениях с gRPC-сервером.
59 В значении параметра допустимо использование переменных.
60 Специальное значение <literal>off</literal> отменяет действие
61 унаследованной с предыдущего уровня конфигурации
62 директивы <literal>grpc_bind</literal>, позволяя системе
63 самостоятельно выбирать локальный IP-адрес и порт.
64 </para>
65
66 <para id="grpc_bind_transparent">
67 Параметр <literal>transparent</literal> позволяет
68 задать нелокальный IP-aдрес, который будет использоваться в
69 исходящих соединениях с gRPC-сервером,
70 например, реальный IP-адрес клиента:
71 <example>
72 grpc_bind $remote_addr transparent;
73 </example>
74 Для работы параметра
75 обычно требуется
76 запустить рабочие процессы nginx с привилегиями
77 <link doc="../ngx_core_module.xml" id="user">суперпользователя</link>.
78 В Linux этого не требуется, так как если
79 указан параметр <literal>transparent</literal>, то рабочие процессы
80 наследуют capability <literal>CAP_NET_RAW</literal> из главного процесса.
81 Также необходимо настроить таблицу маршрутизации ядра
82 для перехвата сетевого трафика с gRPC-сервера.
83 </para>
84
85 </directive>
86
87
88 <directive name="grpc_buffer_size">
89 <syntax><value>размер</value></syntax>
90 <default>4k|8k</default>
91 <context>http</context>
92 <context>server</context>
93 <context>location</context>
94
95 <para>
96 Задаёт <value>размер</value> буфера, в который будет читаться ответ,
97 получаемый от gRPC-сервера.
98 Ответ синхронно передаётся клиенту сразу же по мере его поступления.
99 </para>
100
101 </directive>
102
103
104 <directive name="grpc_connect_timeout">
105 <syntax><value>время</value></syntax>
106 <default>60s</default>
107 <context>http</context>
108 <context>server</context>
109 <context>location</context>
110
111 <para>
112 Задаёт таймаут для установления соединения с gRPC-сервером.
113 Необходимо иметь в виду, что этот таймаут обычно не может превышать 75 секунд.
114 </para>
115
116 </directive>
117
118
119 <directive name="grpc_hide_header">
120 <syntax><value>поле</value></syntax>
121 <default/>
122 <context>http</context>
123 <context>server</context>
124 <context>location</context>
125
126 <para>
127 По умолчанию
128 nginx не передаёт клиенту поля заголовка <header>Date</header>,
129 <header>Server</header> и
130 <header>X-Accel-...</header> из ответа gRPC-сервера.
131 Директива <literal>grpc_hide_header</literal> задаёт дополнительные поля,
132 которые не будут передаваться.
133 Если же передачу полей нужно разрешить, можно воспользоваться
134 директивой <link id="grpc_pass_header"/>.
135 </para>
136
137 </directive>
138
139
140 <directive name="grpc_ignore_headers">
141 <syntax><value>поле</value> ...</syntax>
142 <default/>
143 <context>http</context>
144 <context>server</context>
145 <context>location</context>
146
147 <para>
148 Запрещает обработку некоторых полей заголовка из ответа gRPC-сервера.
149 В директиве можно указать поля <header>X-Accel-Redirect</header>
150 и <header>X-Accel-Charset</header>.
151 </para>
152
153 <para>
154 Если не запрещено, обработка этих полей заголовка заключается в следующем:
155 <list type="bullet" compact="no">
156
157 <listitem>
158 <header>X-Accel-Redirect</header> производит
159 <link doc="ngx_http_core_module.xml" id="internal">внутреннее
160 перенаправление</link> на указанный URI;
161 </listitem>
162
163 <listitem>
164 <header>X-Accel-Charset</header> задаёт желаемую
165 <link doc="ngx_http_charset_module.xml" id="charset">кодировку</link>
166 ответа.
167 </listitem>
168
169 </list>
170 </para>
171
172 </directive>
173
174
175 <directive name="grpc_intercept_errors">
176 <syntax><literal>on</literal> | <literal>off</literal></syntax>
177 <default>off</default>
178 <context>http</context>
179 <context>server</context>
180 <context>location</context>
181
182 <para>
183 Определяет, передавать ли клиенту ответы gRPC-сервера с кодом
184 больше либо равным 300,
185 или же перехватывать их и перенаправлять на обработку nginx’у с помощью
186 директивы <link doc="ngx_http_core_module.xml" id="error_page"/>.
187 </para>
188
189 </directive>
190
191
192 <directive name="grpc_next_upstream">
193 <syntax>
194 <literal>error</literal> |
195 <literal>timeout</literal> |
196 <literal>invalid_header</literal> |
197 <literal>http_500</literal> |
198 <literal>http_502</literal> |
199 <literal>http_503</literal> |
200 <literal>http_504</literal> |
201 <literal>http_403</literal> |
202 <literal>http_404</literal> |
203 <literal>http_429</literal> |
204 <literal>non_idempotent</literal> |
205 <literal>off</literal>
206 ...</syntax>
207 <default>error timeout</default>
208 <context>http</context>
209 <context>server</context>
210 <context>location</context>
211
212 <para>
213 Определяет, в каких случаях запрос будет передан следующему серверу:
214 <list type="tag">
215
216 <tag-name><literal>error</literal></tag-name>
217 <tag-desc>произошла ошибка соединения с сервером, передачи ему запроса или
218 чтения заголовка ответа сервера;</tag-desc>
219
220 <tag-name><literal>timeout</literal></tag-name>
221 <tag-desc>произошёл таймаут во время соединения с сервером,
222 передачи ему запроса или чтения заголовка ответа сервера;</tag-desc>
223
224 <tag-name><literal>invalid_header</literal></tag-name>
225 <tag-desc>сервер вернул пустой или неверный ответ;</tag-desc>
226
227 <tag-name><literal>http_500</literal></tag-name>
228 <tag-desc>сервер вернул ответ с кодом 500;</tag-desc>
229
230 <tag-name><literal>http_502</literal></tag-name>
231 <tag-desc>сервер вернул ответ с кодом 502;</tag-desc>
232
233 <tag-name><literal>http_503</literal></tag-name>
234 <tag-desc>сервер вернул ответ с кодом 503;</tag-desc>
235
236 <tag-name><literal>http_504</literal></tag-name>
237 <tag-desc>сервер вернул ответ с кодом 504;</tag-desc>
238
239 <tag-name><literal>http_403</literal></tag-name>
240 <tag-desc>сервер вернул ответ с кодом 403;</tag-desc>
241
242 <tag-name><literal>http_404</literal></tag-name>
243 <tag-desc>сервер вернул ответ с кодом 404;</tag-desc>
244
245 <tag-name><literal>http_429</literal></tag-name>
246 <tag-desc>сервер вернул ответ с кодом 429;</tag-desc>
247
248 <tag-name id="non_idempotent"><literal>non_idempotent</literal></tag-name>
249 <tag-desc>обычно запросы с
250 <link url="https://tools.ietf.org/html/rfc7231#section-4.2.2">неидемпотентным</link>
251 методом
252 (<literal>POST</literal>, <literal>LOCK</literal>, <literal>PATCH</literal>)
253 не передаются на другой сервер,
254 если запрос серверу группы уже был отправлен;
255 включение параметра явно разрешает повторять подобные запросы;
256 </tag-desc>
257
258
259 <tag-name><literal>off</literal></tag-name>
260 <tag-desc>запрещает передачу запроса следующему серверу.</tag-desc>
261
262 </list>
263 </para>
264
265 <para>
266 Необходимо понимать, что передача запроса следующему серверу возможна
267 только при условии, что клиенту ещё ничего не передавалось.
268 То есть, если ошибка или таймаут возникли в середине передачи ответа,
269 то исправить это уже невозможно.
270 </para>
271
272 <para>
273 Директива также определяет, что считается
274 <link doc="ngx_http_upstream_module.xml" id="max_fails">неудачной
275 попыткой</link> работы с сервером.
276 Случаи <literal>error</literal>, <literal>timeout</literal> и
277 <literal>invalid_header</literal>
278 всегда считаются неудачными попытками, даже если они не указаны в директиве.
279 Случаи <literal>http_500</literal>, <literal>http_502</literal>,
280 <literal>http_503</literal>, <literal>http_504</literal>
281 и <literal>http_429</literal>
282 считаются неудачными попытками, только если они указаны в директиве.
283 Случаи <literal>http_403</literal> и <literal>http_404</literal>
284 никогда не считаются неудачными попытками.
285 </para>
286
287 <para>
288 Передача запроса следующему серверу может быть ограничена по
289 <link id="grpc_next_upstream_tries">количеству попыток</link>
290 и по <link id="grpc_next_upstream_timeout">времени</link>.
291 </para>
292
293 </directive>
294
295
296 <directive name="grpc_next_upstream_timeout">
297 <syntax><value>время</value></syntax>
298 <default>0</default>
299 <context>http</context>
300 <context>server</context>
301 <context>location</context>
302
303 <para>
304 Ограничивает время, в течение которого возможна передача запроса
305 <link id="grpc_next_upstream">следующему серверу</link>.
306 Значение <literal>0</literal> отключает это ограничение.
307 </para>
308
309 </directive>
310
311
312 <directive name="grpc_next_upstream_tries">
313 <syntax><value>число</value></syntax>
314 <default>0</default>
315 <context>http</context>
316 <context>server</context>
317 <context>location</context>
318
319 <para>
320 Ограничивает число допустимых попыток для передачи запроса
321 <link id="grpc_next_upstream">следующему серверу</link>.
322 Значение <literal>0</literal> отключает это ограничение.
323 </para>
324
325 </directive>
326
327
328 <directive name="grpc_pass">
329 <syntax><value>адрес</value></syntax>
330 <default/>
331 <context>location</context>
332 <context>if в location</context>
333
334 <para>
335 Задаёт адрес gRPC-сервера.
336 Адрес может быть указан в виде доменного имени или IP-адреса,
337 и порта:
338 <example>
339 grpc_pass localhost:9000;
340 </example>
341 или в виде пути UNIX-сокета:
342 <example>
343 grpc_pass unix:/tmp/grpc.socket;
344 </example>
345 Также может использоваться схема “<literal>grpc://</literal>”:
346 <example>
347 grpc_pass grpc://127.0.0.1:9000;
348 </example>
349 Для использования gRPC по SSL необходимо использовать схему
350 “<literal>grpcs://</literal>”:
351 <example>
352 grpc_pass grpcs://127.0.0.1:443;
353 </example>
354 </para>
355
356 <para>
357 Если доменному имени соответствует несколько адресов, то все они будут
358 использоваться по очереди (round-robin).
359 И, кроме того, адрес может быть
360 <link doc="ngx_http_upstream_module.xml">группой серверов</link>.
361 </para>
362
363 </directive>
364
365
366 <directive name="grpc_pass_header">
367 <syntax><value>поле</value></syntax>
368 <default/>
369 <context>http</context>
370 <context>server</context>
371 <context>location</context>
372
373 <para>
374 Разрешает передавать от gRPC-сервера клиенту
375 <link id="grpc_hide_header">запрещённые для передачи</link> поля заголовка.
376 </para>
377
378 </directive>
379
380
381 <directive name="grpc_read_timeout">
382 <syntax><value>время</value></syntax>
383 <default>60s</default>
384 <context>http</context>
385 <context>server</context>
386 <context>location</context>
387
388 <para>
389 Задаёт таймаут при чтении ответа gRPC-сервера.
390 Таймаут устанавливается не на всю передачу ответа,
391 а только между двумя операциями чтения.
392 Если по истечении этого времени gRPC-сервер ничего не передаст,
393 соединение закрывается.
394 </para>
395
396 </directive>
397
398
399 <directive name="grpc_send_timeout">
400 <syntax><value>время</value></syntax>
401 <default>60s</default>
402 <context>http</context>
403 <context>server</context>
404 <context>location</context>
405
406 <para>
407 Задаёт таймаут при передаче запроса gRPC-серверу.
408 Таймаут устанавливается не на всю передачу запроса,
409 а только между двумя операциями записи.
410 Если по истечении этого времени gRPC-сервер не примет новых данных,
411 соединение закрывается.
412 </para>
413
414 </directive>
415
416
417 <directive name="grpc_set_header">
418 <syntax><value>поле</value> <value>значение</value></syntax>
419 <default>Content-Length $content_length</default>
420 <context>http</context>
421 <context>server</context>
422 <context>location</context>
423
424 <para>
425 Позволяет переопределять или добавлять поля заголовка запроса,
426 <link id="proxy_pass_request_headers">передаваемые</link> gRPC-серверу.
427 В качестве значения можно использовать текст, переменные и их комбинации.
428 Директивы наследуются с предыдущего уровня при условии, что на данном
429 уровне не описаны свои директивы <literal>grpc_set_header</literal>.
430 </para>
431
432 <para>
433 Если значение поля заголовка — пустая строка, то поле вообще
434 не будет передаваться gRPC-серверу:
435 <example>
436 grpc_set_header Accept-Encoding "";
437 </example>
438 </para>
439
440 </directive>
441
442
443 <directive name="grpc_ssl_certificate">
444 <syntax><value>файл</value></syntax>
445 <default/>
446 <context>http</context>
447 <context>server</context>
448 <context>location</context>
449
450 <para>
451 Задаёт <value>файл</value> с сертификатом в формате PEM
452 для аутентификации на gRPC SSL-сервере.
453 </para>
454
455 </directive>
456
457
458 <directive name="grpc_ssl_certificate_key">
459 <syntax><value>файл</value></syntax>
460 <default/>
461 <context>http</context>
462 <context>server</context>
463 <context>location</context>
464
465 <para>
466 Задаёт <value>файл</value> с секретным ключом в формате PEM
467 для аутентификации на gRPC SSL-сервере.
468 </para>
469
470 <para>
471 Вместо <value>файла</value> можно указать значение
472 <literal>engine</literal>:<value>имя</value>:<value>id</value>,
473 которое загружает ключ с указанным <value>id</value>
474 из OpenSSL engine с заданным <value>именем</value>.
475 </para>
476
477 </directive>
478
479
480 <directive name="grpc_ssl_ciphers">
481 <syntax><value>шифры</value></syntax>
482 <default>DEFAULT</default>
483 <context>http</context>
484 <context>server</context>
485 <context>location</context>
486
487 <para>
488 Описывает разрешённые шифры для запросов к gRPC SSL-серверу.
489 Шифры задаются в формате, поддерживаемом библиотекой OpenSSL.
490 </para>
491
492 <para>
493 Полный список можно посмотреть с помощью команды
494 “<command>openssl ciphers</command>”.
495 </para>
496
497 </directive>
498
499
500 <directive name="grpc_ssl_crl">
501 <syntax><value>файл</value></syntax>
502 <default/>
503 <context>http</context>
504 <context>server</context>
505 <context>location</context>
506
507 <para>
508 Указывает <value>файл</value> с отозванными сертификатами (CRL)
509 в формате PEM, используемыми при <link id="proxy_ssl_verify">проверке</link>
510 сертификата gRPC SSL-сервера.
511 </para>
512
513 </directive>
514
515
516 <directive name="grpc_ssl_name">
517 <syntax><value>имя</value></syntax>
518 <default>имя хоста из grpc_pass</default>
519 <context>http</context>
520 <context>server</context>
521 <context>location</context>
522
523 <para>
524 Позволяет переопределить имя сервера, используемое при
525 <link id="grpc_ssl_verify">проверке</link>
526 сертификата gRPC SSL-сервера, а также для
527 <link id="grpc_ssl_server_name">передачи его через SNI</link>
528 при установлении соединения с gRPC SSL-сервером.
529 </para>
530
531 <para>
532 По умолчанию используется имя хоста из <link id="grpc_pass"/>.
533 </para>
534
535 </directive>
536
537
538 <directive name="grpc_ssl_password_file">
539 <syntax><value>файл</value></syntax>
540 <default/>
541 <context>http</context>
542 <context>server</context>
543 <context>location</context>
544
545 <para>
546 Задаёт <value>файл</value> с паролями от
547 <link id="grpc_ssl_certificate_key">секретных ключей</link>,
548 где каждый пароль указан на отдельной строке.
549 Пароли применяются по очереди в момент загрузки ключа.
550 </para>
551
552 </directive>
553
554
555 <directive name="grpc_ssl_server_name">
556 <syntax><literal>on</literal> | <literal>off</literal></syntax>
557 <default>off</default>
558 <context>http</context>
559 <context>server</context>
560 <context>location</context>
561
562 <para>
563 Разрешает или запрещает передачу имени сервера через
564 <link url="http://en.wikipedia.org/wiki/Server_Name_Indication">расширение
565 Server Name Indication протокола TLS</link> (SNI, RFC 6066)
566 при установлении соединения с gRPC SSL-сервером.
567 </para>
568
569 </directive>
570
571
572 <directive name="grpc_ssl_session_reuse">
573 <syntax><literal>on</literal> | <literal>off</literal></syntax>
574 <default>on</default>
575 <context>http</context>
576 <context>server</context>
577 <context>location</context>
578
579 <para>
580 Определяет, использовать ли повторно SSL-сессии при
581 работе с gRPC-сервером.
582 Если в логах появляются ошибки
583 “<literal>SSL3_GET_FINISHED:digest check failed</literal>”,
584 то можно попробовать выключить
585 повторное использование сессий.
586 </para>
587
588 </directive>
589
590
591 <directive name="grpc_ssl_protocols">
592 <syntax>
593 [<literal>SSLv2</literal>]
594 [<literal>SSLv3</literal>]
595 [<literal>TLSv1</literal>]
596 [<literal>TLSv1.1</literal>]
597 [<literal>TLSv1.2</literal>]
598 [<literal>TLSv1.3</literal>]</syntax>
599 <default>TLSv1 TLSv1.1 TLSv1.2</default>
600 <context>http</context>
601 <context>server</context>
602 <context>location</context>
603
604 <para>
605 Разрешает указанные протоколы для запросов к gRPC SSL-серверу.
606 </para>
607
608 </directive>
609
610
611 <directive name="grpc_ssl_trusted_certificate">
612 <syntax><value>файл</value></syntax>
613 <default/>
614 <context>http</context>
615 <context>server</context>
616 <context>location</context>
617
618 <para>
619 Задаёт <value>файл</value> с доверенными сертификатами CA в формате PEM,
620 используемыми при <link id="grpc_ssl_verify">проверке</link>
621 сертификата gRPC SSL-сервера.
622 </para>
623
624 </directive>
625
626
627 <directive name="grpc_ssl_verify">
628 <syntax><literal>on</literal> | <literal>off</literal></syntax>
629 <default>off</default>
630 <context>http</context>
631 <context>server</context>
632 <context>location</context>
633
634 <para>
635 Разрешает или запрещает проверку сертификата gRPC SSL-сервера.
636 </para>
637
638 </directive>
639
640
641 <directive name="grpc_ssl_verify_depth">
642 <syntax><value>число</value></syntax>
643 <default>1</default>
644 <context>http</context>
645 <context>server</context>
646 <context>location</context>
647
648 <para>
649 Устанавливает глубину проверки в цепочке сертификатов
650 gRPC SSL-сервера.
651 </para>
652
653 </directive>
654
655 </section>
656
657 </module>