Mercurial > hg > nginx-site

comparison xml/ru/docs/http/ngx_http_v3_module.xml @ 2956:a85e4d126bc7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated docs for the upcoming NGINX Plus release.
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 02 May 2023 11:39:21 +0100
parents
children cebca5ba84d7
comparison
equal deleted inserted replaced
2955:2c4d7151b9a9 2956:a85e4d126bc7
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Модуль ngx_http_v3_module"
10 link="/ru/docs/http/ngx_http_v3_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 Модуль <literal>ngx_http_v3_module</literal> (1.23.4) обеспечивает
18 экспериментальную поддержку
19 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>.
20 </para>
21
22 <para>
23 По умолчанию этот модуль не собирается, его сборку необходимо
24 разрешить с помощью конфигурационного параметра
25 <link doc="../configure.xml"><literal>--with-http_v3_module</literal></link>.
26 <note>
27 Для сборки и работы этого модуля рекомендуется использовать
28 библиотеку SSL с поддержкой QUIC, например
29 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>,
30 <link url="https://www.libressl.org">LibreSSL</link>,
31 <link url="https://github.com/quictls/openssl">QuicTLS</link>.
32 Иначе,
33 при использовании библиотеки <link url="https://openssl.org">OpenSSL</link>,
34 будет использоваться OpenSSL compatibility layer,
35 в котором не поддерживается
36 <link doc="ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>.
37 </note>
38 </para>
39
40 <para>
41 <note>
42 Модуль доступен в виде
43 <link doc="../quic.xml" id="linux">готовых пакетов</link>
44 <literal>nginx-quic</literal> для Linux.
45 Модуль также доступен как часть
46 <commercial_version>коммерческой подписки</commercial_version>
47 в виде отдельного пакета <literal>nginx-plus-http3</literal>.
48
49 </note>
50 </para>
51
52 </section>
53
54
55 <section id="issues" name="Известные проблемы">
56
57 <para>
58 Модуль экспериментальный, поэтому возможно всё.
59 </para>
60
61 </section>
62
63
64 <section id="example" name="Пример конфигурации">
65
66 <para>
67 <example>
68 http {
69 log_format quic '$remote_addr - $remote_user [$time_local] '
70 '"$request" $status $body_bytes_sent '
71 '"$http_referer" "$http_user_agent" "$http3"';
72
73 access_log logs/access.log quic;
74
75 server {
76 # для лучшей совместимости рекомендуется
77 # использовать одинаковый порт для http/3 и https
78 listen 8443 quic reuseport;
79 listen 8443 ssl;
80
81 ssl_certificate certs/example.com.crt;
82 ssl_certificate_key certs/example.com.key;
83
84 location / {
85 # используется для объявления о поддержке http/3
86 add_header Alt-Svc 'h3=":8443"; ma=86400';
87 }
88 }
89 }
90 </example>
91 Чтобы принимать HTTP/3-соединения по TLS, необходимо
92 наличие поддержки протокола TLSv1.3, появившейся в
93 <link url="http://www.openssl.org">OpenSSL</link> версии 1.1.1.
94 </para>
95
96 </section>
97
98
99 <section id="directives" name="Директивы">
100
101 <directive name="http3">
102 <syntax><literal>on</literal> | <literal>off</literal></syntax>
103 <default>on</default>
104 <context>http</context>
105 <context>server</context>
106
107 <para>
108 Разрешает
109 согласование протокола
110 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>.
111 </para>
112
113 </directive>
114
115
116 <directive name="http3_hq">
117 <syntax><literal>on</literal> | <literal>off</literal></syntax>
118 <default>off</default>
119 <context>http</context>
120 <context>server</context>
121
122 <para>
123 Разрешает согласование протокола HTTP/0.9,
124 используемого в
125 <link url="https://github.com/marten-seemann/quic-interop-runner">функциональных
126 тестах QUIC</link>.
127 </para>
128
129 </directive>
130
131
132 <directive name="http3_max_concurrent_pushes">
133 <syntax><value>число</value></syntax>
134 <default>10</default>
135 <context>http</context>
136 <context>server</context>
137
138 <para>
139 Ограничивает максимальное число параллельных
140 <link id="http3_push">push</link>-запросов в соединении.
141 </para>
142
143 </directive>
144
145
146 <directive name="http3_max_concurrent_streams">
147 <syntax><value>число</value></syntax>
148 <default>128</default>
149 <context>http</context>
150 <context>server</context>
151
152 <para>
153 Задаёт максимальное число параллельных HTTP/3-потоков
154 в соединении.
155 </para>
156
157 </directive>
158
159
160 <directive name="http3_push">
161 <syntax><value>uri</value> | <literal>off</literal></syntax>
162 <default>off</default>
163 <context>http</context>
164 <context>server</context>
165 <context>location</context>
166
167 <para>
168 Заблаговременно отправляет
169 (<link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link>) запрос
170 к заданному <value>uri</value>
171 вместе с ответом на оригинальный запрос.
172 Будут обработаны только относительные URI с абсолютными путями,
173 например:
174 <example>
175 http3_push /static/css/main.css;
176 </example>
177 В значении <value>uri</value> допустимо использование переменных.
178 </para>
179
180 <para>
181 На одном уровне конфигурации можно указать несколько
182 <literal>http3_push</literal> директив.
183 Параметр <literal>off</literal> отменяет действие
184 унаследованных с предыдущего уровня конфигурации
185 директив <literal>http3_push</literal>.
186 </para>
187
188 </directive>
189
190
191 <directive name="http3_push_preload">
192 <syntax><literal>on</literal> | <literal>off</literal></syntax>
193 <default>off</default>
194 <context>http</context>
195 <context>server</context>
196 <context>location</context>
197
198 <para>
199 Разрешает автоматическое преобразование
200 <link url="https://www.w3.org/TR/preload/#server-push-http-3">preload
201 links</link>,
202 указанных в полях <header>Link</header> заголовка ответа, в
203 <link url="https://datatracker.ietf.org/doc/html/rfc9114#name-server-push">push</link>-запросы.
204 </para>
205
206 </directive>
207
208
209 <directive name="http3_stream_buffer_size">
210 <syntax><value>размер</value></syntax>
211 <default>64k</default>
212 <context>http</context>
213 <context>server</context>
214
215 <para>
216 Задаёт размер буфера, используемого для чтения и записи
217 QUIC-потоков.
218 </para>
219
220 </directive>
221
222
223 <directive name="quic_active_connection_id_limit">
224 <syntax><value>число</value></syntax>
225 <default>2</default>
226 <context>http</context>
227 <context>server</context>
228
229 <para>
230 Устанавливает
231 значение транспортного параметра QUIC <literal>active_connection_id_limit</literal>.
232 Это максимальное значение ID соединений,
233 возможное для хранения на сервере.
234 </para>
235
236 </directive>
237
238
239 <directive name="quic_bpf">
240 <syntax><literal>on</literal> | <literal>off</literal></syntax>
241 <default>off</default>
242 <context>main</context>
243
244 <para>
245 Разрешает маршрутизацию пакетов QUIC при помощи
246 <link url="https://ebpf.io/">eBPF</link>.
247 Если маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений.
248 </para>
249
250 <para>
251 <note>
252 Директива поддерживается только на Linux 5.7+.
253 </note>
254 </para>
255
256 </directive>
257
258
259 <directive name="quic_gso">
260 <syntax><literal>on</literal> | <literal>off</literal></syntax>
261 <default>off</default>
262 <context>http</context>
263 <context>server</context>
264
265 <para>
266 Разрешает отправку оптимизированного пакетного режима
267 при помощи segmentation offloading.
268 </para>
269
270 <para>
271 <note>
272 Оптимизированная отправка поддерживается только на Linux
273 с поддержкой <literal>UDP_SEGMENT</literal>.
274 </note>
275 </para>
276
277 </directive>
278
279
280 <directive name="quic_host_key">
281 <syntax><value>файл</value></syntax>
282 <default/>
283 <context>http</context>
284 <context>server</context>
285
286 <para>
287 Задаёт <value>файл</value> с секретным ключом, применяемым при шифровании
288 stateless reset и address validation токенов.
289 По умолчанию создаётся случайный ключ при каждой перезагрузке.
290 Токены, созданные при помощи старых ключей, не принимаются.
291 </para>
292
293 </directive>
294
295
296 <directive name="quic_mtu">
297 <syntax><value>размер</value></syntax>
298 <default>65527</default>
299 <context>http</context>
300 <context>server</context>
301
302 <para>
303 Устанавливает
304 значение транспортного параметра QUIC <literal>max_udp_payload_size</literal>.
305 Это максимально возможное значение для получения UDP payload.
306 </para>
307
308 </directive>
309
310
311 <directive name="quic_retry">
312 <syntax><literal>on</literal> | <literal>off</literal></syntax>
313 <default>off</default>
314 <context>http</context>
315 <context>server</context>
316
317 <para>
318 Разрешает функциональность
319 <link url="https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation">QUIC
320 Address Validation</link>,
321 в том числе отправку нового токена в <literal>Retry</literal>-пакете
322 или <literal>NEW_TOKEN</literal> frame
323 и
324 валидацию токена, полученного в <literal>Initial</literal>-пакете.
325 </para>
326
327 </directive>
328
329 </section>
330
331
332 <section id="variables" name="Встроенные переменные">
333
334 <para>
335 Модуль <literal>ngx_http_v3_module</literal>
336 поддерживает следующие встроенные переменные:
337 <list type="tag" compact="no">
338
339 <tag-name id="var_http3"><var>$http3</var></tag-name>
340 <tag-desc>
341 согласованный идентификатор протокола:
342 “<literal>h3</literal>” для HTTP/3-соединений,
343 “<literal>hq</literal>” для hq-соединений,
344 либо пустая строка.
345 </tag-desc>
346
347 </list>
348 </para>
349
350 </section>
351
352 </module>