Mercurial > hg > nginx-site
comparison xml/en/docs/quic.xml @ 2964:23eedf89fd5d
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 | cebca5ba84d7 |
children |
comparison
equal
deleted
inserted
replaced
2963:c7bf5c9a1174 | 2964:23eedf89fd5d |
---|---|
5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> | 5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> |
6 | 6 |
7 <article name="Support for QUIC and HTTP/3" | 7 <article name="Support for QUIC and HTTP/3" |
8 link="/en/docs/quic.html" | 8 link="/en/docs/quic.html" |
9 lang="en" | 9 lang="en" |
10 rev="1"> | 10 rev="2"> |
11 | 11 |
12 <section> | 12 <section> |
13 | 13 |
14 <para> | 14 <para> |
15 Support for | |
15 <link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link> | 16 <link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link> |
16 and | 17 and |
17 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> | 18 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> |
18 protocols are supported since 1.23.4 and are available | 19 protocols is available since 1.25.0. |
19 as a separate <literal>nginx-quic</literal> | 20 Also, since 1.25.0, the QUIC and HTTP/3 support is available in |
20 <link id="linux">prebult Linux package</link> | 21 Linux <link doc="../linux_packages.xml">binary packages</link>. |
21 or as part of our | |
22 <commercial_version>commercial subscription</commercial_version> | |
23 in a separate <literal>nginx-plus-http3</literal> package. | |
24 </para> | 22 </para> |
25 | 23 |
26 <para> | 24 <para> |
27 <note> | 25 <note> |
28 The QUIC and HTTP/3 support is experimental, caveat emptor applies. | 26 The QUIC and HTTP/3 support is experimental, caveat emptor applies. |
30 </para> | 28 </para> |
31 | 29 |
32 </section> | 30 </section> |
33 | 31 |
34 | 32 |
35 <section id="linux" name="Installation on Linux"> | |
36 | |
37 <para> | |
38 For Linux, <literal>nginx-quic</literal> packages | |
39 from nginx.org can be used. | |
40 The packages | |
41 are available for the following Linux distributions and | |
42 versions: | |
43 <list type="bullet"> | |
44 | |
45 <listitem> | |
46 <link id="rhel">RHEL 9 and derivatives</link>: amd64, arm64 | |
47 </listitem> | |
48 | |
49 <listitem> | |
50 <link id="rhel">Ubuntu 22.04</link>: amd64, arm64 | |
51 </listitem> | |
52 | |
53 </list> | |
54 </para> | |
55 | |
56 <para> | |
57 The <literal>nginx-quic</literal> packages are dynamically linked with the | |
58 <link url="https://github.com/quictls/openssl">QuicTLS</link> library. | |
59 It will be installed as a runtime dependency | |
60 alongside system-wide OpenSSL packages. | |
61 QuicTLS differs from operating system-provided OpenSSL package in the following: | |
62 <list type="bullet"> | |
63 | |
64 <listitem> | |
65 does not follow system-wide crypto policies | |
66 </listitem> | |
67 | |
68 <listitem> | |
69 does not have distribution-specific patches applied | |
70 </listitem> | |
71 | |
72 <listitem> | |
73 uses configuration from <literal>/etc/pki/quictls</literal> (RHEL9) | |
74 or <literal>/etc/quictls</literal> (Ubuntu 22.04) | |
75 </listitem> | |
76 | |
77 </list> | |
78 </para> | |
79 | |
80 <para> | |
81 The <literal>nginx-quic</literal> packages | |
82 cannot be installed alongside nginx or nginx-plus packages. | |
83 </para> | |
84 | |
85 <para> | |
86 Please back up your configuration files | |
87 before installing <literal>nginx-quic</literal>: | |
88 <programlisting> | |
89 sudo cp -a /etc/nginx /etc/nginx-quic-backup | |
90 </programlisting> | |
91 </para> | |
92 | |
93 | |
94 <section name="RHEL" id="rhel"> | |
95 | |
96 <para> | |
97 The <literal>nginx-quic</literal> package can be installed on | |
98 Red Hat Enterprise Linux and its derivatives such as | |
99 CentOS, Oracle Linux, Rocky Linux, AlmaLinux. | |
100 </para> | |
101 | |
102 <para> | |
103 Install the prerequisites: | |
104 <programlisting> | |
105 sudo dnf install yum-utils | |
106 </programlisting> | |
107 | |
108 To set up the yum repository, create the file named | |
109 <path>/etc/yum.repos.d/nginx-quic.repo </path> | |
110 with the following contents: | |
111 | |
112 <programlisting> | |
113 [nginx-quic] | |
114 name=nginx-quic repo | |
115 baseurl=https://packages.nginx.org/nginx-quic/rhel/9/$basearch/ | |
116 gpgcheck=1 | |
117 enabled=1 | |
118 gpgkey=https://nginx.org/keys/nginx_signing.key | |
119 </programlisting> | |
120 | |
121 To install nginx-quic, run the following commands: | |
122 <programlisting> | |
123 sudo dnf install nginx-quic | |
124 </programlisting> | |
125 | |
126 When prompted to accept the GPG key, verify that the fingerprint matches | |
127 <command>573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62</command>, | |
128 and if so, accept it. | |
129 </para> | |
130 | |
131 </section> | |
132 | |
133 | |
134 <section name="Ubuntu" id="ubuntu"> | |
135 | |
136 <para> | |
137 Install the prerequisites: | |
138 <programlisting> | |
139 sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring | |
140 </programlisting> | |
141 </para> | |
142 | |
143 <para> | |
144 Import an official nginx signing key so apt could verify the packages | |
145 authenticity. | |
146 Fetch the key: | |
147 <programlisting> | |
148 curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ | |
149 | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null | |
150 </programlisting> | |
151 | |
152 To set up the apt repository for nginx-quic packages, run the following command: | |
153 <programlisting> | |
154 echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ | |
155 https://packages.nginx.org/nginx-quic/ubuntu `lsb_release -cs` nginx-quic" \ | |
156 | sudo tee /etc/apt/sources.list.d/nginx-quic.list | |
157 </programlisting> | |
158 </para> | |
159 | |
160 <para> | |
161 To install nginx-quic, run the following commands: | |
162 <programlisting> | |
163 sudo apt update | |
164 sudo apt install nginx-quic | |
165 </programlisting> | |
166 </para> | |
167 | |
168 </section> | |
169 | |
170 </section> | |
171 | |
172 | |
173 <section id="building" name="Building from sources"> | 33 <section id="building" name="Building from sources"> |
174 | 34 |
175 <para> | 35 <para> |
176 The build is configured using the <command>configure</command> command. | 36 The build is configured using the <command>configure</command> command. |
177 Please refer to <link doc="configure.xml"/> for details. | 37 Please refer to <link doc="configure.xml"/> for details. |
178 </para> | 38 </para> |
179 | 39 |
180 <para> | 40 <para> |
181 When configuring nginx, it is possible to enable QUIC and HTTP/3 | 41 When configuring nginx, it is possible to enable QUIC and HTTP/3 using the |
182 using the following configuration options: | 42 <link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link> |
183 | 43 configuration parameter. |
184 <list type="tag"> | |
185 | |
186 <tag-name> | |
187 <literal>--with-http_v3_module</literal><br/> | |
188 </tag-name> | |
189 <tag-desc> | |
190 enables QUIC and HTTP/3. | |
191 </tag-desc> | |
192 | |
193 </list> | |
194 </para> | 44 </para> |
195 | 45 |
196 <para> | 46 <para> |
197 An SSL library that provides QUIC support is recommended to build nginx, such as | 47 An SSL library that provides QUIC support is recommended to build nginx, such as |
198 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, | 48 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, |
205 | 55 |
206 <para> | 56 <para> |
207 Use the following command to configure nginx with | 57 Use the following command to configure nginx with |
208 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>: | 58 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>: |
209 <programlisting> | 59 <programlisting> |
210 ./auto/configure --with-debug --with-http_v3_module \ | 60 ./configure |
211 --with-cc-opt="-I../boringssl/include" \ | 61 --with-debug |
212 --with-ld-opt="-L../boringssl/build/ssl \ | 62 --with-http_v3_module |
213 -L../boringssl/build/crypto" | 63 --with-cc-opt="-I../boringssl/include" |
64 --with-ld-opt="-L../boringssl/build/ssl | |
65 -L../boringssl/build/crypto" | |
214 </programlisting> | 66 </programlisting> |
215 </para> | 67 </para> |
216 | 68 |
217 <para> | 69 <para> |
218 Alternatively, nginx can be configured with | 70 Alternatively, nginx can be configured with |
219 <link url="https://github.com/quictls/openssl">QuicTLS</link>: | 71 <link url="https://github.com/quictls/openssl">QuicTLS</link>: |
220 <programlisting> | 72 <programlisting> |
221 ./auto/configure --with-debug --with-http_v3_module \ | 73 ./configure |
222 --with-cc-opt="-I../quictls/build/include" \ | 74 --with-debug |
223 --with-ld-opt="-L../quictls/build/lib" | 75 --with-http_v3_module |
76 --with-cc-opt="-I../quictls/build/include" | |
77 --with-ld-opt="-L../quictls/build/lib" | |
224 </programlisting> | 78 </programlisting> |
225 </para> | 79 </para> |
226 | 80 |
227 <para> | 81 <para> |
228 Alternatively, nginx can be configured with a modern version of | 82 Alternatively, nginx can be configured with a modern version of |
229 <link url="https://www.libressl.org">LibreSSL</link>: | 83 <link url="https://www.libressl.org">LibreSSL</link>: |
230 <programlisting> | 84 <programlisting> |
231 ./auto/configure --with-debug --with-http_v3_module \ | 85 ./configure |
232 --with-cc-opt="-I../libressl/build/include" \ | 86 --with-debug |
233 --with-ld-opt="-L../libressl/build/lib" | 87 --with-http_v3_module |
88 --with-cc-opt="-I../libressl/build/include" | |
89 --with-ld-opt="-L../libressl/build/lib" | |
234 </programlisting> | 90 </programlisting> |
235 </para> | 91 </para> |
236 | 92 |
237 <para> | 93 <para> |
238 After configuration, | 94 After configuration, |
258 <link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link> | 114 <link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link> |
259 parameter to make it work properly with multiple workers. | 115 parameter to make it work properly with multiple workers. |
260 </para> | 116 </para> |
261 | 117 |
262 <para> | 118 <para> |
119 For the list of directives, see | |
120 <link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>. | |
121 </para> | |
122 | |
123 <para> | |
263 To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link> | 124 To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link> |
264 address validation: | 125 address validation: |
265 <programlisting> | 126 <programlisting> |
266 quic_retry on; | 127 quic_retry on; |
267 </programlisting> | 128 </programlisting> |
276 GSO (Generic Segmentation Offloading): | 137 GSO (Generic Segmentation Offloading): |
277 <programlisting> | 138 <programlisting> |
278 quic_gso on; | 139 quic_gso on; |
279 </programlisting> | 140 </programlisting> |
280 | 141 |
281 To <link doc="http/ngx_http_v3_module.xml" id="quic_mtu">limit</link> | |
282 maximum UDP payload size on receive path: | |
283 <programlisting> | |
284 quic_mtu <size>; | |
285 </programlisting> | |
286 | |
287 To <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">set</link> | 142 To <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">set</link> |
288 host key for various tokens: | 143 host key for various tokens: |
289 <programlisting> | 144 <programlisting> |
290 quic_host_key <filename>; | 145 quic_host_key <filename>; |
291 </programlisting> | 146 </programlisting> |
292 | |
293 </para> | 147 </para> |
294 | 148 |
295 <para> | 149 <para> |
296 QUIC requires TLSv1.3 protocol version which is enabled by default | 150 QUIC requires TLSv1.3 protocol version which is enabled by default |
297 in the <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/> directive. | 151 in the <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/> directive. |
327 | 181 |
328 ssl_certificate certs/example.com.crt; | 182 ssl_certificate certs/example.com.crt; |
329 ssl_certificate_key certs/example.com.key; | 183 ssl_certificate_key certs/example.com.key; |
330 | 184 |
331 location / { | 185 location / { |
332 # required for browsers to direct them into quic port | 186 # required for browsers to direct them to quic port |
333 add_header Alt-Svc 'h3=":8443"; ma=86400'; | 187 add_header Alt-Svc 'h3=":8443"; ma=86400'; |
334 } | 188 } |
335 } | 189 } |
336 } | 190 } |
337 </example> | 191 </example> |
338 </para> | 192 </para> |
339 | 193 |
340 </section> | 194 </section> |
341 | 195 |
342 | 196 |
343 <section id="directives" name="Directives"> | |
344 | |
345 <para> | |
346 For the list of directives, please refer to | |
347 <link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link> | |
348 module documentation. | |
349 </para> | |
350 | |
351 </section> | |
352 | |
353 | |
354 <section id="troubleshooting " name="Troubleshooting"> | 197 <section id="troubleshooting " name="Troubleshooting"> |
355 | 198 |
356 <para> | 199 <para> |
357 Tips that may help to identify problems: | 200 Tips that may help to identify problems: |
358 <list type="bullet"> | 201 <list type="bullet"> |
359 | 202 |
360 <listitem> | 203 <listitem> |
361 Ensure nginx is built with the proper SSL library that supports QUIC. | 204 Ensure nginx is built with the proper SSL library. |
362 </listitem> | 205 </listitem> |
363 | 206 |
364 <listitem> | 207 <listitem> |
365 Ensure nginx is using the proper SSL library in runtime | 208 Ensure nginx is using the proper SSL library in runtime |
366 (the <literal>nginx -V</literal> shows what it is currently used). | 209 (the <literal>nginx -V</literal> shows what it is currently used). |
367 </listitem> | 210 </listitem> |
368 | 211 |
369 <listitem> | 212 <listitem> |
370 Ensure a client is actually sending requests over QUIC. | 213 Ensure a client is actually sending requests over QUIC. |
371 We recommend starting with a simple console client such as | 214 It is recommended to start with a simple console client such as |
372 <link url="https://nghttp2.org/ngtcp2">ngtcp2</link> | 215 <link url="https://nghttp2.org/ngtcp2">ngtcp2</link> |
373 to ensure the server is configured properly before trying | 216 to ensure the server is configured properly before trying |
374 with real browsers that may be quite picky with certificates. | 217 with real browsers that may be quite picky with certificates. |
375 </listitem> | 218 </listitem> |
376 | 219 |
381 All related messages contain the “<literal>quic</literal>” prefix | 224 All related messages contain the “<literal>quic</literal>” prefix |
382 and can be easily filtered out. | 225 and can be easily filtered out. |
383 </listitem> | 226 </listitem> |
384 | 227 |
385 <listitem> | 228 <listitem> |
386 For a deeper investigation, please enable additional debugging in | 229 For a deeper investigation, additional debugging can be enabled |
387 <literal>src/event/quic/ngx_event_quic_connection.h</literal>: | 230 using the following macros: |
388 | 231 <literal>NGX_QUIC_DEBUG_PACKETS</literal>, |
389 <para> | 232 <literal>NGX_QUIC_DEBUG_FRAMES</literal>, |
390 <example> | 233 <literal>NGX_QUIC_DEBUG_ALLOC</literal>, |
391 #define NGX_QUIC_DEBUG_PACKETS | 234 <literal>NGX_QUIC_DEBUG_CRYPTO</literal>. |
392 #define NGX_QUIC_DEBUG_FRAMES | 235 |
393 #define NGX_QUIC_DEBUG_ALLOC | 236 <para> |
394 #define NGX_QUIC_DEBUG_CRYPTO | 237 <programlisting> |
395 </example> | 238 ./configure |
239 --with-http_v3_module | |
240 --with-debug | |
241 --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" | |
242 </programlisting> | |
396 </para> | 243 </para> |
397 </listitem> | 244 </listitem> |
398 | 245 |
399 </list> | 246 </list> |
400 </para> | 247 </para> |
401 | 248 |
402 </section> | 249 </section> |
403 | 250 |
404 | |
405 <section id="contributing" name="Contributing"> | |
406 | |
407 <para> | |
408 Please refer to <link doc="contributing_changes.xml"/>. | |
409 </para> | |
410 | |
411 </section> | |
412 | |
413 </article> | 251 </article> |