Mercurial > hg > nginx-site
comparison xml/ru/docs/http/ngx_http_v3_module.xml @ 2956:a85e4d126bc7
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> |