Mercurial > hg > nginx-site
comparison xml/en/docs/quic.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 <!-- | |
2 Copyright (C) Nginx, Inc. | |
3 --> | |
4 | |
5 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> | |
6 | |
7 <article name="Support for QUIC and HTTP/3" | |
8 link="/en/docs/quic.html" | |
9 lang="en" | |
10 rev="1"> | |
11 | |
12 <section> | |
13 | |
14 <para> | |
15 <link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link> | |
16 and | |
17 <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> | |
18 protocols are supported since 1.23.4 and are available | |
19 as a separate <literal>nginx-quic</literal> | |
20 <link id="linux">prebult Linux package</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> | |
25 | |
26 <para> | |
27 <note> | |
28 The QUIC and HTTP/3 support is experimental, caveat emptor applies. | |
29 </note> | |
30 </para> | |
31 | |
32 </section> | |
33 | |
34 | |
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 and 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"> | |
174 | |
175 <para> | |
176 The build is configured using the <command>configure</command> command. | |
177 Please refer to <link doc="configure.xml"/> for details. | |
178 </para> | |
179 | |
180 <para> | |
181 When configuring nginx, it is possible to enable QUIC and HTTP/3 | |
182 using the following configuration options: | |
183 | |
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> | |
195 | |
196 <para> | |
197 An SSL library that provides QUIC support is recommended to build nginx, such as | |
198 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>, | |
199 <link url="https://www.libressl.org">LibreSSL</link>, or | |
200 <link url="https://github.com/quictls/openssl">QuicTLS</link>. | |
201 Otherwise, the <link url="https://openssl.org">OpenSSL</link> | |
202 compatibility layer will be used that does not support | |
203 <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">early data</link>. | |
204 </para> | |
205 | |
206 <para> | |
207 Use the following command to configure nginx with | |
208 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>: | |
209 <programlisting> | |
210 ./auto/configure --with-debug --with-http_v3_module \ | |
211 --with-cc-opt="-I../boringssl/include" \ | |
212 --with-ld-opt="-L../boringssl/build/ssl \ | |
213 -L../boringssl/build/crypto" | |
214 </programlisting> | |
215 </para> | |
216 | |
217 <para> | |
218 Alternatively, nginx can be configured with | |
219 <link url="https://github.com/quictls/openssl">QuicTLS</link>: | |
220 <programlisting> | |
221 ./auto/configure --with-debug --with-http_v3_module \ | |
222 --with-cc-opt="-I../quictls/build/include" \ | |
223 --with-ld-opt="-L../quictls/build/lib" | |
224 </programlisting> | |
225 </para> | |
226 | |
227 <para> | |
228 Alternatively, nginx can be configured with a modern version of | |
229 <link url="https://www.libressl.org">LibreSSL</link>: | |
230 <programlisting> | |
231 ./auto/configure --with-debug --with-http_v3_module \ | |
232 --with-cc-opt="-I../libressl/build/include" \ | |
233 --with-ld-opt="-L../libressl/build/lib" | |
234 </programlisting> | |
235 </para> | |
236 | |
237 <para> | |
238 After configuration, | |
239 nginx is compiled and installed using <command>make</command>. | |
240 </para> | |
241 | |
242 </section> | |
243 | |
244 | |
245 <section id="configuration" name="Configuration"> | |
246 | |
247 <para> | |
248 The <link doc="http/ngx_http_core_module.xml" id="listen"/> directive in | |
249 <link doc="http/ngx_http_core_module.xml">ngx_http_core_module</link> | |
250 module got a new parameter | |
251 <link doc="http/ngx_http_core_module.xml" id="quic">quic</link> | |
252 which enables HTTP/3 over QUIC on the specified port. | |
253 </para> | |
254 | |
255 <para> | |
256 Along with the <literal>quic</literal> parameter | |
257 it is also possible to specify the | |
258 <link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link> | |
259 parameter to make it work properly with multiple workers. | |
260 </para> | |
261 | |
262 <para> | |
263 To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link> | |
264 address validation: | |
265 <programlisting> | |
266 quic_retry on; | |
267 </programlisting> | |
268 | |
269 To <link doc="http/ngx_http_ssl_module.xml" id="ssl_early_data">enable</link> | |
270 0-RTT: | |
271 <programlisting> | |
272 ssl_early_data on; | |
273 </programlisting> | |
274 | |
275 To <link doc="http/ngx_http_v3_module.xml" id="quic_gso">enable</link> | |
276 GSO (Generic Segmentation Offloading): | |
277 <programlisting> | |
278 quic_gso on; | |
279 </programlisting> | |
280 | |
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> | |
288 host key for various tokens: | |
289 <programlisting> | |
290 quic_host_key <filename>; | |
291 </programlisting> | |
292 | |
293 </para> | |
294 | |
295 <para> | |
296 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. | |
298 </para> | |
299 | |
300 <para> | |
301 By default, | |
302 <link url="http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf">GSO Linux-specific optimization</link> | |
303 is disabled. | |
304 Enable it in case a corresponding network interface is configured | |
305 to support GSO. | |
306 </para> | |
307 | |
308 </section> | |
309 | |
310 | |
311 <section id="example" name="Example Configuration"> | |
312 | |
313 <para> | |
314 <example> | |
315 http { | |
316 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
317 '"$request" $status $body_bytes_sent ' | |
318 '"$http_referer" "$http_user_agent" "$http3"'; | |
319 | |
320 access_log logs/access.log quic; | |
321 | |
322 server { | |
323 # for better compatibility it's recommended | |
324 # to use the same port for quic and https | |
325 listen 8443 quic reuseport; | |
326 listen 8443 ssl; | |
327 | |
328 ssl_certificate certs/example.com.crt; | |
329 ssl_certificate_key certs/example.com.key; | |
330 | |
331 location / { | |
332 # required for browsers to direct them into quic port | |
333 add_header Alt-Svc 'h3=":8443"; ma=86400'; | |
334 } | |
335 } | |
336 } | |
337 </example> | |
338 </para> | |
339 | |
340 </section> | |
341 | |
342 | |
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"> | |
355 | |
356 <para> | |
357 Tips that may help to identify problems: | |
358 <list type="bullet"> | |
359 | |
360 <listitem> | |
361 Ensure nginx is built with the proper SSL library that supports QUIC. | |
362 </listitem> | |
363 | |
364 <listitem> | |
365 Ensure nginx is using the proper SSL library in runtime | |
366 (the <literal>nginx -V</literal> shows what it is currently used). | |
367 </listitem> | |
368 | |
369 <listitem> | |
370 Ensure a client is actually sending requests over QUIC | |
371 (see the <link id="clients">Clients</link> section | |
372 for information about browsers and cache). | |
373 We recommend starting with a simple console client such as | |
374 <link url="https://nghttp2.org/ngtcp2">ngtcp2</link> | |
375 to ensure the server is configured properly before trying | |
376 with real browsers that may be quite picky with certificates. | |
377 </listitem> | |
378 | |
379 <listitem> | |
380 Build nginx with <link doc="debugging_log.xml">debug support</link> | |
381 and check the debug log. | |
382 It should contain all details about the connection and why it failed. | |
383 All related messages contain the “<literal>quic</literal>” prefix | |
384 and can be easily filtered out. | |
385 </listitem> | |
386 | |
387 <listitem> | |
388 For a deeper investigation, please enable additional debugging in | |
389 <literal>src/event/quic/ngx_event_quic_connection.h</literal>: | |
390 | |
391 <para> | |
392 <example> | |
393 #define NGX_QUIC_DEBUG_PACKETS | |
394 #define NGX_QUIC_DEBUG_FRAMES | |
395 #define NGX_QUIC_DEBUG_ALLOC | |
396 #define NGX_QUIC_DEBUG_CRYPTO | |
397 </example> | |
398 </para> | |
399 </listitem> | |
400 | |
401 </list> | |
402 </para> | |
403 | |
404 </section> | |
405 | |
406 | |
407 <section id="contributing" name="Contributing"> | |
408 | |
409 <para> | |
410 Please refer to <link doc="contributing_changes.xml"/>. | |
411 </para> | |
412 | |
413 </section> | |
414 | |
415 </article> |