Mercurial > hg > nginx
annotate README @ 9087:6c732b87ee10 quic
HTTP/3: fixed CANCEL_PUSH handling.
author | Sergey Kandaurov <pluknet@nginx.com> |
---|---|
date | Thu, 06 Apr 2023 18:18:41 +0400 |
parents | c851a2ed5ce8 |
children | 8347620e0e76 |
rev | line source |
---|---|
8366 | 1 Experimental QUIC support for nginx |
2 ----------------------------------- | |
3 | |
4 1. Introduction | |
9074 | 5 2. Building from sources |
8366 | 6 3. Configuration |
9074 | 7 4. Directives |
8 5. Clients | |
9 6. Troubleshooting | |
10 7. Contributing | |
11 8. Links | |
8366 | 12 |
13 1. Introduction | |
14 | |
15 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx. | |
16 | |
17 The code is developed in a separate "quic" branch available | |
18 at https://hg.nginx.org/nginx-quic. Currently it is based | |
9021
8d0753760546
Merged with the default branch.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9019
diff
changeset
|
19 on nginx mainline 1.23.x. We merge new nginx releases into |
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
20 this branch regularly. |
8366 | 21 |
22 The project code base is under the same BSD license as nginx. | |
23 | |
9028
98e94553ae51
README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9021
diff
changeset
|
24 The code is currently at a beta level of quality, however |
98e94553ae51
README: updated the current status.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9021
diff
changeset
|
25 there are several production deployments with it. |
8366 | 26 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
27 NGINX Development Team is working on improving HTTP/3 support to |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
28 integrate it into the main NGINX codebase. Thus, expect further |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
29 updates of this code, including features, changes in behaviour, |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
30 bug fixes, and refactoring. NGINX Development team will be |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
31 grateful for any feedback and code submissions. |
8366 | 32 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
33 Please contact NGINX Development Team via nginx-devel mailing list [3]. |
8366 | 34 |
35 What works now: | |
36 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
37 IETF QUIC version 1 is supported. Internet drafts are no longer supported. |
8366 | 38 |
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
39 nginx should be able to respond to HTTP/3 requests over QUIC and |
8366 | 40 it should be possible to upload and download big files without errors. |
41 | |
42 + The handshake completes successfully | |
43 + One endpoint can update keys and its peer responds correctly | |
8390 | 44 + 0-RTT data is being received and acted on |
8366 | 45 + Connection is established using TLS Resume Ticket |
8389
2b580ac17a47
README: Retry support, protocol error messages implemented.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8373
diff
changeset
|
46 + A handshake that includes a Retry packet completes successfully |
8366 | 47 + Stream data is being exchanged and ACK'ed |
48 + An H3 transaction succeeded | |
49 + One or both endpoints insert entries into dynamic table and | |
50 subsequently reference them from header blocks | |
8527 | 51 + Version Negotiation packet is sent to client with unknown version |
52 + Lost packets are detected and retransmitted properly | |
8763
4117aa7fa38e
QUIC: connection migration.
Vladimir Homutov <vl@nginx.com>
parents:
8747
diff
changeset
|
53 + Clients may migrate to new address |
8366 | 54 |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
55 2. Building from sources |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
56 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
57 The build is configured using the configure command. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
58 Refer to http://nginx.org/en/docs/configure.html for details. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
59 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
60 When configuring nginx, it's possible to enable QUIC and HTTP/3 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
61 using the following new configuration options: |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
62 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
63 --with-http_v3_module - enable QUIC and HTTP/3 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
64 --with-stream_quic_module - enable QUIC in Stream |
8366 | 65 |
9080
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
66 A library that provides QUIC support is recommended to build nginx, there |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
67 are several of those available on the market: |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
68 + BoringSSL [4] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
69 + LibreSSL [5] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
70 + QuicTLS [6] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
71 |
9080
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
72 Alternatively, nginx can be configured with OpenSSL compatibility |
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
73 layer, which emulates BoringSSL QUIC API for OpenSSL. This mode is |
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
74 enabled by default if native QUIC support is not detected. |
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
75 0-RTT is not supported in OpenSSL compatibility mode. |
7da4791e0264
QUIC: OpenSSL compatibility layer.
Roman Arutyunyan <arut@nginx.com>
parents:
9074
diff
changeset
|
76 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
77 Clone the NGINX QUIC repository |
8366 | 78 |
8373
796b5b6c43cd
Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8372
diff
changeset
|
79 $ hg clone -b quic https://hg.nginx.org/nginx-quic |
8366 | 80 $ cd nginx-quic |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
81 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
82 Use the following command to configure nginx with BoringSSL [4] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
83 |
8966
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
84 $ ./auto/configure --with-debug --with-http_v3_module \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
85 --with-cc-opt="-I../boringssl/include" \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
86 --with-ld-opt="-L../boringssl/build/ssl \ |
8372
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
87 -L../boringssl/build/crypto" |
8366 | 88 $ make |
89 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
90 Alternatively, nginx can be configured with QuicTLS [6] |
8966
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
91 |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
92 $ ./auto/configure --with-debug --with-http_v3_module \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
93 --with-cc-opt="-I../quictls/build/include" \ |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
94 --with-ld-opt="-L../quictls/build/lib" |
6f8253673669
README: documented QuicTLS support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8929
diff
changeset
|
95 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
96 Alternatively, nginx can be configured with a modern version |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
97 of LibreSSL [7] |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
98 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
99 $ ./auto/configure --with-debug --with-http_v3_module \ |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
100 --with-cc-opt="-I../libressl/build/include" \ |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
101 --with-ld-opt="-L../libressl/build/lib" |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
102 |
8366 | 103 3. Configuration |
104 | |
9081
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
105 The HTTP "listen" directive got a new option "quic" which enables |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
106 QUIC as client transport protocol instead of TCP. |
8366 | 107 |
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
108 The Stream "listen" directive got a new option "quic" which enables |
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
109 QUIC as client transport protocol instead of TCP or plain UDP. |
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
110 |
9081
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
111 Along with "quic", it's also possible to specify "reuseport" |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
112 option [8] to make it work properly with multiple workers. |
8366 | 113 |
8402
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
114 To enable address validation: |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
115 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
116 quic_retry on; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
117 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
118 To enable 0-RTT: |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
119 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
120 ssl_early_data on; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
121 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
122 Make sure that TLS 1.3 is configured which is required for QUIC: |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
123 |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
124 ssl_protocols TLSv1.3; |
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
125 |
8819
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8804
diff
changeset
|
126 To enable GSO (Generic Segmentation Offloading): |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8804
diff
changeset
|
127 |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8804
diff
changeset
|
128 quic_gso on; |
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8804
diff
changeset
|
129 |
9019
0e74a77c2475
README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8984
diff
changeset
|
130 To limit maximum UDP payload size on receive path: |
8924
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
131 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
132 quic_mtu <size>; |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
133 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
134 To set host key for various tokens: |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
135 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
136 quic_host_key <filename>; |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
137 |
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
138 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
139 By default, GSO Linux-specific optimization [10] is disabled. |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
140 Enable it in case a corresponding network interface is configured to |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
141 support GSO. |
8819
d0ef43a53a51
QUIC: updated README with GSO details.
Vladimir Homutov <vl@nginx.com>
parents:
8804
diff
changeset
|
142 |
8498
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
143 A number of directives were added that configure HTTP/3: |
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
144 |
9081
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
145 http3 |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
146 http3_hq |
8924
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
147 http3_stream_buffer_size |
8498
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
148 http3_max_concurrent_pushes |
8924
d6ef13c5fd8e
QUIC: simplified configuration.
Vladimir Homutov <vl@nginx.com>
parents:
8923
diff
changeset
|
149 http3_max_concurrent_streams |
8498
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
150 http3_push |
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
151 http3_push_preload |
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
152 |
8923
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8922
diff
changeset
|
153 In http, an additional variable is available: $http3. |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8922
diff
changeset
|
154 The value of $http3 is "h3" for HTTP/3 connections, |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8922
diff
changeset
|
155 "hq" for hq connections, or an empty string otherwise. |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8922
diff
changeset
|
156 |
651cc905b7c2
HTTP/3: $http3 variable.
Roman Arutyunyan <arut@nginx.com>
parents:
8922
diff
changeset
|
157 In stream, an additional variable is available: $quic. |
8366 | 158 The value of $quic is "quic" if QUIC connection is used, |
8788
f0882db8c8d4
HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8787
diff
changeset
|
159 or an empty string otherwise. |
8366 | 160 |
161 Example configuration: | |
162 | |
163 http { | |
164 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
165 '"$request" $status $body_bytes_sent ' | |
8929 | 166 '"$http_referer" "$http_user_agent" "$http3"'; |
8366 | 167 |
168 access_log logs/access.log quic; | |
169 | |
170 server { | |
171 # for better compatibility it's recommended | |
172 # to use the same port for quic and https | |
9081
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
173 listen 8443 quic reuseport; |
8366 | 174 listen 8443 ssl; |
175 | |
176 ssl_certificate certs/example.com.crt; | |
177 ssl_certificate_key certs/example.com.key; | |
178 ssl_protocols TLSv1.3; | |
179 | |
180 location / { | |
181 # required for browsers to direct them into quic port | |
8788
f0882db8c8d4
HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8787
diff
changeset
|
182 add_header Alt-Svc 'h3=":8443"; ma=86400'; |
8366 | 183 } |
184 } | |
185 } | |
186 | |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
187 4. Directives |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
188 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
189 Syntax: quic_bpf on | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
190 Default: quic_bpf off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
191 Context: main |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
192 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
193 Enables routing of QUIC packets using eBPF. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
194 When enabled, this allows to support QUIC connection migration. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
195 The directive is only supported on Linux 5.7+. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
196 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
197 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
198 Syntax: quic_retry on | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
199 Default: quic_retry off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
200 Context: http | stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
201 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
202 Enables the QUIC Address Validation feature. This includes: |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
203 - sending a new token in a Retry packet or a NEW_TOKEN frame |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
204 - validating a token received in the Initial packet |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
205 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
206 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
207 Syntax: quic_gso on | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
208 Default: quic_gso off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
209 Context: http | stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
210 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
211 Enables sending in optimized batch mode using segmentation offloading. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
212 Optimized sending is only supported on Linux featuring UDP_SEGMENT. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
213 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
214 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
215 Syntax: quic_mtu size; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
216 Default: quic_mtu 65527; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
217 Context: http | stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
218 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
219 Sets the QUIC max_udp_payload_size transport parameter value. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
220 This is the maximum UDP payload that we are willing to receive. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
221 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
222 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
223 Syntax: quic_host_key file; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
224 Default: - |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
225 Context: http | stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
226 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
227 Specifies a file with the secret key used to encrypt stateless reset and |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
228 address validation tokens. By default, a randomly generated key is used. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
229 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
230 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
231 Syntax: quic_active_connection_id_limit number; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
232 Default: quic_active_connection_id_limit 2; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
233 Context: http | stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
234 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
235 Sets the QUIC active_connection_id_limit transport parameter value. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
236 This is the maximum number of connection IDs we are willing to store. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
237 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
238 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
239 Syntax: quic_timeout time; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
240 Default: quic_timeout 60s; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
241 Context: stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
242 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
243 Defines a timeout used to negotiate the QUIC idle timeout. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
244 In the http module, it is taken from the keepalive_timeout directive. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
245 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
246 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
247 Syntax: quic_stream_buffer_size size; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
248 Default: quic_stream_buffer_size 64k; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
249 Context: stream, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
250 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
251 Syntax: http3_stream_buffer_size size; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
252 Default: http3_stream_buffer_size 64k; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
253 Context: http, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
254 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
255 Sets buffer size for reading and writing of the QUIC STREAM payload. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
256 The buffer size is used to calculate initial flow control limits |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
257 in the following QUIC transport parameters: |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
258 - initial_max_data |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
259 - initial_max_stream_data_bidi_local |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
260 - initial_max_stream_data_bidi_remote |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
261 - initial_max_stream_data_uni |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
262 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
263 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
264 Syntax: http3_max_concurrent_pushes number; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
265 Default: http3_max_concurrent_pushes 10; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
266 Context: http, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
267 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
268 Limits the maximum number of concurrent push requests in a connection. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
269 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
270 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
271 Syntax: http3_max_concurrent_streams number; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
272 Default: http3_max_concurrent_streams 128; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
273 Context: http, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
274 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
275 Sets the maximum number of concurrent HTTP/3 streams in a connection. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
276 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
277 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
278 Syntax: http3_push uri | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
279 Default: http3_push off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
280 Context: http, server, location |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
281 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
282 Pre-emptively sends (pushes) a request to the specified uri along with |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
283 the response to the original request. Only relative URIs with absolute |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
284 path will be processed, for example: |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
285 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
286 http3_push /static/css/main.css; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
287 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
288 The uri value can contain variables. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
289 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
290 Several http3_push directives can be specified on the same configuration |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
291 level. The off parameter cancels the effect of the http3_push directives |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
292 inherited from the previous configuration level. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
293 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
294 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
295 Syntax: http3_push_preload on | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
296 Default: http3_push_preload off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
297 Context: http, server, location |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
298 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
299 Enables automatic conversion of preload links specified in the “Link” |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
300 response header fields into push requests. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
301 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
302 |
9081
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
303 Syntax: http3 on | off; |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
304 Default: http3 on; |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
305 Context: http, server |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
306 |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
307 Enables HTTP/3 protocol negotiation. |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
308 |
c851a2ed5ce8
HTTP/3: "quic" parameter of "listen" directive.
Roman Arutyunyan <arut@nginx.com>
parents:
9080
diff
changeset
|
309 |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
310 Syntax: http3_hq on | off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
311 Default: http3_hq off; |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
312 Context: http, server |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
313 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
314 Enables HTTP/0.9 protocol negotiation used in QUIC interoperability tests. |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
315 |
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
316 5. Clients |
8366 | 317 |
318 * Browsers | |
319 | |
8982
8f5d0ade0da7
README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8966
diff
changeset
|
320 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1) |
8366 | 321 |
322 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
323 Cache clearing/restart might help. Always check access.log and | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
324 error.log to make sure the browser is using HTTP/3 and not TCP https. |
8366 | 325 |
326 * Console clients | |
327 | |
328 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
329 | |
330 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
331 | |
332 $ ./neqo-client https://127.0.0.1:8443/ | |
333 | |
8982
8f5d0ade0da7
README: updated to QUICv1.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8966
diff
changeset
|
334 $ chromium-build/out/my_build/quic_client http://example.com:8443 |
8366 | 335 |
336 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
337 In case everyhing is right, the access log should show something like: |
8366 | 338 |
339 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" | |
8788
f0882db8c8d4
HTTP/3: removed $http3 that served its purpose.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8787
diff
changeset
|
340 "nghttp3/ngtcp2 client" "quic" |
8366 | 341 |
342 | |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
343 6. Troubleshooting |
8366 | 344 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
345 Here are some tips that may help to identify problems: |
8366 | 346 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
347 + Ensure nginx is built with proper SSL library that supports QUIC |
8366 | 348 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
349 + Ensure nginx is using the proper SSL library in runtime |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
350 (`nginx -V` shows what it's using) |
8366 | 351 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
352 + Ensure a client is actually sending requests over QUIC |
8366 | 353 (see "Clients" section about browsers and cache) |
354 | |
355 We recommend to start with simple console client like ngtcp2 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
356 to ensure the server is configured properly before trying |
8395 | 357 with real browsers that may be very picky with certificates, |
8366 | 358 for example. |
359 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
360 + Build nginx with debug support [9] and check the debug log. |
8366 | 361 It should contain all details about connection and why it |
362 failed. All related messages contain "quic " prefix and can | |
363 be easily filtered out. | |
364 | |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
365 + For a deeper investigation, please enable additional debugging |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
366 in src/event/quic/ngx_event_quic_connection.h: |
8366 | 367 |
368 #define NGX_QUIC_DEBUG_PACKETS | |
369 #define NGX_QUIC_DEBUG_FRAMES | |
8657
2dfc5ef29973
QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents:
8601
diff
changeset
|
370 #define NGX_QUIC_DEBUG_ALLOC |
8366 | 371 #define NGX_QUIC_DEBUG_CRYPTO |
372 | |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
373 7. Contributing |
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
374 |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
375 Please refer to |
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
376 http://nginx.org/en/docs/contributing_changes.html |
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
377 |
9073
3c33d39a51d3
README: updated building from sources, added directives reference.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9034
diff
changeset
|
378 8. Links |
8366 | 379 |
8787
8422570f6af4
README: updated after QUIC RFC publication, nginx 1.21 rebase.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8763
diff
changeset
|
380 [1] https://datatracker.ietf.org/doc/html/rfc9000 |
9019
0e74a77c2475
README: updated after HTTP/3 RFC publication, minor refinements.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8984
diff
changeset
|
381 [2] https://datatracker.ietf.org/doc/html/rfc9114 |
9074 | 382 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel |
8366 | 383 [4] https://boringssl.googlesource.com/boringssl/ |
9034
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
384 [5] https://www.libressl.org/ |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
385 [6] https://github.com/quictls/openssl |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
386 [7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0 |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
387 [8] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
388 [9] https://nginx.org/en/docs/debugging_log.html |
79cd6993a3e3
README: converted to passive voice, LibreSSL support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
9028
diff
changeset
|
389 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf |