Mercurial > hg > nginx-site

comparison xml/ru/docs/quic.xml @ 2964:23eedf89fd5d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated QUIC documentation after QUIC code merge. - removed http3_max_concurrent_pushes, http3_push http3_push_preload, quic_mtu - updated apperared-in version - update of quic.xml, adding Rus translation
author Yaroslav Zhuravlev <yar@nginx.com>
date Tue, 23 May 2023 16:44:47 +0100
parents
children
comparison
equal deleted inserted replaced
2963:c7bf5c9a1174 2964:23eedf89fd5d
1 <!--
2 Copyright (C) Nginx, Inc.
3 -->
4
5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
6
7 <article name="Поддержка QUIC и HTTP/3"
8 link="/ru/docs/quic.html"
9 lang="ru"
10 rev="2">
11
12 <section>
13
14 <para>
15 Поддержка протоколов
16 <link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link>
17 и
18 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link>
19 доступна начиная с версии 1.25.0.
20 Также, начиная с 1.25.0, поддержка доступна в
21 <link doc="../linux_packages.xml">готовых пакетах</link> для Linux.
22 </para>
23
24 <para>
25 <note>
26 Поддержка QUIC и HTTP/3 экспериментальная, поэтому возможно всё.
27 </note>
28 </para>
29
30 </section>
31
32
33 <section id="building" name="Сборка из исходных файлов">
34
35 <para>
36 Сборка настраивается командой <command>configure</command>.
37 Подробнее см. в статье <link doc="configure.xml"/>.
38 </para>
39
40 <para>
41 Во время сборки nginx можно включить QUIC и HTTP/3
42 при помощи конфигурационного параметра
43 <link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>.
44 </para>
45
46 <para>
47 Для сборки nginx рекомендуется библиотека SSL с поддержкой QUIC, например
48 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>,
49 <link url="https://www.libressl.org">LibreSSL</link> или
50 <link url="https://github.com/quictls/openssl">QuicTLS</link>.
51 Иначе, при использовании библиотеки <link url="https://openssl.org">OpenSSL</link>,
52 будет использоваться OpenSSL compatibility layer, в котором не поддерживается
53 <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>.
54 </para>
55
56 <para>
57 При конфигурации nginx с
58 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>
59 используется следующая команда:
60 <programlisting>
61 ./configure
62 --with-debug
63 --with-http_v3_module
64 --with-cc-opt="-I../boringssl/include"
65 --with-ld-opt="-L../boringssl/build/ssl
66 -L../boringssl/build/crypto"
67 </programlisting>
68 </para>
69
70 <para>
71 Кроме того, можно сконфигурировать nginx с
72 <link url="https://github.com/quictls/openssl">QuicTLS</link>:
73 <programlisting>
74 ./configure
75 --with-debug
76 --with-http_v3_module
77 --with-cc-opt="-I../quictls/build/include"
78 --with-ld-opt="-L../quictls/build/lib"
79 </programlisting>
80 </para>
81
82 <para>
83 Кроме того, можно сконфигурировать nginx с современной версией
84 <link url="https://www.libressl.org">LibreSSL</link>:
85 <programlisting>
86 ./configure
87 --with-debug
88 --with-http_v3_module
89 --with-cc-opt="-I../libressl/build/include"
90 --with-ld-opt="-L../libressl/build/lib"
91 </programlisting>
92 </para>
93
94 <para>
95 После конфигурации
96 nginx компилируется и устанавливается с помощью
97 <command>make</command>.
98 </para>
99
100 </section>
101
102
103 <section id="configuration" name="Конфигурация">
104
105 <para>
106 В директиве <link doc="http/ngx_http_core_module.xml" id="listen"/>
107 модуля <link doc="http/ngx_http_core_module.xml">ngx_http_core_module</link>
108 появился новый параметр
109 <link doc="http/ngx_http_core_module.xml" id="quic">quic</link>,
110 который позволяет принимать на указанном порту QUIC-соединения.
111 </para>
112
113 <para>
114 Вместе с параметром <literal>quic</literal>
115 можно также указать параметр
116 <link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link>
117 для правильной работы с несколькими рабочими процессами.
118 </para>
119
120 <para>
121 Список директив см. в модуле
122 <link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>.
123 </para>
124
125 <para>
126 Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_retry">разрешить</link>
127 проверку адреса:
128 <programlisting>
129 quic_retry on;
130 </programlisting>
131
132 Чтобы <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">разрешить</link>
133 0-RTT:
134 <programlisting>
135 ssl_early_data on;
136 </programlisting>
137
138 Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_gso">разрешить</link>
139 GSO (Generic Segmentation Offloading):
140 <programlisting>
141 quic_gso on;
142 </programlisting>
143
144 Чтобы <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">установить</link>
145 host-ключ для различных токенов:
146 <programlisting>
147 quic_host_key &lt;filename&gt;;
148 </programlisting>
149 </para>
150
151 <para>
152 Для работы QUIC требуется версия протокла TLSv1.3, которая включена по умолчанию
153 в директиве <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/>.
154 </para>
155
156 <para>
157 По умолчанию
158 <link url="http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf">GSO Linux-specific optimization</link>
159 выключена.
160 Включите, если настроен соответствующий сетевой интерфейс,
161 поддерживающий GSO.
162 </para>
163
164 </section>
165
166
167 <section id="example" name="Пример конфигурации">
168
169 <para>
170 <example>
171 http {
172 log_format quic '$remote_addr - $remote_user [$time_local] '
173 '"$request" $status $body_bytes_sent '
174 '"$http_referer" "$http_user_agent" "$http3"';
175
176 access_log logs/access.log quic;
177
178 server {
179 # для лучшей совместимости рекомендуется
180 # использовать один порт для quic и https
181 listen 8443 quic reuseport;
182 listen 8443 ssl;
183
184 ssl_certificate certs/example.com.crt;
185 ssl_certificate_key certs/example.com.key;
186
187 location / {
188 # для перенаправления браузеров в quic-порт
189 add_header Alt-Svc 'h3=":8443"; ma=86400';
190 }
191 }
192 }
193 </example>
194 </para>
195
196 </section>
197
198
199 <section id="troubleshooting " name="Устранение неполадок">
200
201 <para>
202 Приблизительные шаги при обнаружении проблемы:
203 <list type="bullet">
204
205 <listitem>
206 Убедитесь, что nginx собран с правильной SSL-библиотекой.
207 </listitem>
208
209 <listitem>
210 Убедитесь, что nginx использует правильную SSL-библиотеку в runtime
211 (<literal>nginx -V</literal> покажет что именно используется в данный момент).
212 </listitem>
213
214 <listitem>
215 Убедитесь, что клиент действительно присылает запросы через QUIC.
216 Рекомендуется начать с простого консольного клиента, например
217 <link url="https://nghttp2.org/ngtcp2">ngtcp2</link>,
218 чтобы убедиться, что сервер настроен правильно, и затем попробовать
219 в браузерах, так как браузеры могут быть требовательны к сертификатам.
220 </listitem>
221
222 <listitem>
223 Соберите nginx с поддержкой <link doc="debugging_log.xml">отладочного лога</link>
224 и проверьте отладочный лог.
225 В нём должны содержаться все детали соединения и причины ошибок.
226 Соответствующие сообщения начинаются с префикса “<literal>quic</literal>”
227 и могут быть по нему отфильтрованы.
228 </listitem>
229
230 <listitem>
231 Для детального исследования можно включить дополнительную отладку
232 при помощи следующих макросов:
233 <literal>NGX_QUIC_DEBUG_PACKETS</literal>,
234 <literal>NGX_QUIC_DEBUG_FRAMES</literal>,
235 <literal>NGX_QUIC_DEBUG_ALLOC</literal>,
236 <literal>NGX_QUIC_DEBUG_CRYPTO</literal>.
237
238 <para>
239 <programlisting>
240 ./configure
241 --with-http_v3_module
242 --with-debug
243 --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"
244 </programlisting>
245 </para>
246
247 </listitem>
248
249 </list>
250 </para>
251
252 </section>
253
254 </article>