Mercurial > hg > nginx
annotate README @ 8555:8b6486f0fe79 quic
QUIC: switch stream context to a server selected by SNI.
Previously the default server configuration context was used until the
:authority or host header was parsed. This led to using the configuration
parameters like client_header_buffer_size or request_pool_size from the default
server rather than from the server selected by SNI.
Also, the switch to the right server log is implemented. This issue manifested
itself as QUIC stream being logged to the default server log until :authority
or host is parsed.
| author | Roman Arutyunyan <arut@nginx.com> |
|---|---|
| date | Tue, 29 Sep 2020 22:09:09 +0100 |
| parents | 57e5393e5d40 |
| children | dd8e50e11bfc |
| rev | line source |
|---|---|
| 8366 | 1 Experimental QUIC support for nginx |
| 2 ----------------------------------- | |
| 3 | |
| 4 1. Introduction | |
| 5 2. Installing | |
| 6 3. Configuration | |
| 7 4. Clients | |
| 8 5. Troubleshooting | |
|
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
9 6. Contributing |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
10 7. Links |
| 8366 | 11 |
| 12 1. Introduction | |
| 13 | |
| 14 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx. | |
| 15 | |
| 16 The code is developed in a separate "quic" branch available | |
| 17 at https://hg.nginx.org/nginx-quic. Currently it is based | |
|
8412
4ea302a47d28
README: update after merging 1.19.0.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8410
diff
changeset
|
18 on nginx mainline 1.19.x. We are planning to merge new nginx |
| 8366 | 19 releases into this branch regularly. |
| 20 | |
| 21 The project code base is under the same BSD license as nginx. | |
| 22 | |
| 23 The code is at an early alpha level of quality and should not | |
| 24 be used in production. | |
| 25 | |
| 26 We are working on improving HTTP/3 support with the goal of | |
| 27 integrating it to the main NGINX codebase. Expect frequent | |
| 28 updates of this code and don't rely on it for whatever purpose. | |
| 29 | |
| 30 We'll be grateful for any feedback and code submissions however | |
| 31 we don't bear any responsibilities for any issues with this code. | |
| 32 | |
| 33 You can always contact us via nginx-devel mailing list [3]. | |
| 34 | |
| 35 What works now: | |
| 36 | |
|
8449
3c32717d7bb2
README: documented draft-28, draft-29 support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8412
diff
changeset
|
37 Currently we support IETF-QUIC draft-27, draft-28, draft-29. |
|
3c32717d7bb2
README: documented draft-28, draft-29 support.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8412
diff
changeset
|
38 Earlier drafts are NOT supported as they have incompatible wire format. |
| 8366 | 39 |
|
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
40 You may look at src/event/ngx_event_quic.h for alternative values of the |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
41 NGX_QUIC_DRAFT_VERSION macro used to select IETF draft version number. |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
42 |
| 8366 | 43 nginx should be able to respond to simple HTTP/3 requests over QUIC and |
| 44 it should be possible to upload and download big files without errors. | |
| 45 | |
| 46 + The handshake completes successfully | |
| 47 + One endpoint can update keys and its peer responds correctly | |
| 8390 | 48 + 0-RTT data is being received and acted on |
| 8366 | 49 + 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
|
50 + A handshake that includes a Retry packet completes successfully |
| 8366 | 51 + Stream data is being exchanged and ACK'ed |
| 52 + An H3 transaction succeeded | |
| 53 + One or both endpoints insert entries into dynamic table and | |
| 54 subsequently reference them from header blocks | |
| 8527 | 55 + Version Negotiation packet is sent to client with unknown version |
| 56 + Lost packets are detected and retransmitted properly | |
| 8366 | 57 |
| 58 Not (yet) supported features: | |
| 59 | |
| 8527 | 60 - Explicit Congestion Notification (ECN) as specified in quic-recovery [5] |
| 8366 | 61 - A connection with the spin bit succeeds and the bit is spinning |
| 62 - Structured Logging | |
| 63 - NAT Rebinding | |
| 64 - Address Mobility | |
| 65 - HTTP/3 trailers | |
| 66 | |
| 67 Since the code is experimental and still under development, | |
| 68 a lot of things may not work as expected, for example: | |
| 69 | |
| 70 - ACK handling is basic: every received ack-eliciting packet | |
| 71 is acknowledged, no ack ranges are used | |
| 72 | |
| 73 - Flow control mechanism is basic and intended to avoid CPU hog and make | |
| 74 simple interactions possible | |
| 75 | |
| 76 - Not all draft requirements are strictly followed; some of checks are | |
| 77 omitted for the sake of simplicity of initial implementation | |
| 78 | |
| 79 2. Installing | |
| 80 | |
| 81 You will need a BoringSSL [4] library that provides QUIC support | |
| 82 | |
|
8373
796b5b6c43cd
Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8372
diff
changeset
|
83 $ hg clone -b quic https://hg.nginx.org/nginx-quic |
| 8366 | 84 $ cd nginx-quic |
|
8372
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
85 $ ./auto/configure --with-debug --with-http_v3_module \ |
|
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
86 --with-cc-opt="-I../boringssl/include" \ |
|
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
87 --with-ld-opt="-L../boringssl/build/ssl \ |
|
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
88 -L../boringssl/build/crypto" |
| 8366 | 89 $ make |
| 90 | |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
91 When configuring nginx, you can enable QUIC and HTTP/3 using the |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
92 following new configuration options: |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
93 |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
94 --with-http_v3_module - enable QUIC and HTTP/3 |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
95 --with-http_quic_module - enable QUIC for older HTTP versions |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
96 --with-stream_quic_module - enable QUIC in Stream |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
97 |
| 8366 | 98 3. Configuration |
| 99 | |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
100 The HTTP "listen" directive got two new options: "http3" and "quic". |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
101 The "http3" option enables HTTP/3 over QUIC on the specified port. |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
102 The "quic" option enables QUIC for older HTTP versions on this port. |
| 8366 | 103 |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
104 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
|
105 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
|
106 |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
107 Along with "http3" or "quic", you also have to specify "reuseport" |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
108 option [6] to make it work properly with multiple workers. |
| 8366 | 109 |
| 110 A number of directives were added that specify transport parameter values: | |
| 111 | |
| 112 quic_max_idle_timeout | |
| 113 quic_max_ack_delay | |
| 114 quic_max_packet_size | |
| 115 quic_initial_max_data | |
| 116 quic_initial_max_stream_data_bidi_local | |
| 117 quic_initial_max_stream_data_bidi_remote | |
| 118 quic_initial_max_stream_data_uni | |
| 119 quic_initial_max_streams_bidi | |
| 120 quic_initial_max_streams_uni | |
| 121 quic_ack_delay_exponent | |
| 122 quic_active_migration | |
| 123 quic_active_connection_id_limit | |
| 124 | |
|
8402
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
125 To enable address validation: |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
126 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
127 quic_retry on; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
128 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
129 To enable 0-RTT: |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
130 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
131 ssl_early_data on; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
132 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
133 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
|
134 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
135 ssl_protocols TLSv1.3; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
136 |
|
8498
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
137 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
|
138 |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
139 http3_max_field_size |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
140 http3_max_table_capacity |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
141 http3_max_blocked_streams |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
142 http3_max_concurrent_pushes |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
143 http3_push |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
144 http3_push_preload |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
145 |
| 8366 | 146 Two additional variables are available: $quic and $http3. |
| 147 The value of $quic is "quic" if QUIC connection is used, | |
| 148 and empty string otherwise. The value of $http3 is a string | |
| 149 "h3-xx" where "xx" is the supported draft number. | |
| 150 | |
| 151 Example configuration: | |
| 152 | |
| 153 http { | |
| 154 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
| 155 '"$request" $status $body_bytes_sent ' | |
| 156 '"$http_referer" "$http_user_agent" "$quic" "$http3"'; | |
| 157 | |
| 158 access_log logs/access.log quic; | |
| 159 | |
| 160 server { | |
| 161 # for better compatibility it's recommended | |
| 162 # to use the same port for quic and https | |
| 163 listen 8443 http3 reuseport; | |
| 164 listen 8443 ssl; | |
| 165 | |
| 166 ssl_certificate certs/example.com.crt; | |
| 167 ssl_certificate_key certs/example.com.key; | |
| 168 ssl_protocols TLSv1.3; | |
| 169 | |
| 170 location / { | |
| 171 # required for browsers to direct them into quic port | |
|
8396
94c06fe6e159
README: pointed out Alt-Svc "ma" parameter useful with curl.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8395
diff
changeset
|
172 add_header Alt-Svc '$http3=":8443"; ma=86400'; |
| 8366 | 173 } |
| 174 } | |
| 175 } | |
| 176 | |
| 177 4. Clients | |
| 178 | |
| 179 * Browsers | |
| 180 | |
| 181 Known to work: Firefox 75+ and Chrome 83+ | |
| 182 | |
| 183 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
| 184 Cache clearing/restart might help. Always check access.log and | |
| 185 error.log to make sure you are using HTTP/3 and not TCP https. | |
| 186 | |
| 187 + to enable QUIC in Firefox, set the following in 'about:config': | |
| 188 network.http.http3.enabled = true | |
| 189 | |
| 190 + to enable QUIC in Chrome, enable it on command line and force it | |
| 191 on your site: | |
| 192 | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
193 $ ./chrome --enable-quic --quic-version=h3-29 \ |
| 8366 | 194 --origin-to-force-quic-on=example.com:8443 |
| 195 | |
| 196 * Console clients | |
| 197 | |
| 198 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
| 199 | |
| 200 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
| 201 | |
| 202 $ ./neqo-client https://127.0.0.1:8443/ | |
| 203 | |
| 204 $ chromium-build/out/my_build/quic_client http://example.com:8443 \ | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
205 --quic_version=h3-29 \ |
| 8366 | 206 --allow_unknown_root_cert \ |
| 207 --disable_certificate_verification | |
| 208 | |
| 209 | |
| 210 If you've got it right, in the access log you should see something like: | |
| 211 | |
| 212 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
213 "nghttp3/ngtcp2 client" "quic" "h3-29" |
| 8366 | 214 |
| 215 | |
| 216 5. Troubleshooting | |
| 217 | |
| 218 Here are some tips that may help you to identify problems: | |
| 219 | |
| 220 + Ensure you are building with proper SSL library that | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
221 implements draft 29 |
| 8366 | 222 |
| 223 + Ensure you are using the proper SSL library in runtime | |
| 224 (`nginx -V` will show you what you are using) | |
| 225 | |
| 226 + Ensure your client is actually sending QUIC requests | |
| 227 (see "Clients" section about browsers and cache) | |
| 228 | |
| 229 We recommend to start with simple console client like ngtcp2 | |
| 230 to ensure you've got server configured properly before trying | |
| 8395 | 231 with real browsers that may be very picky with certificates, |
| 8366 | 232 for example. |
| 233 | |
| 234 + Build nginx with debug support [7] and check your debug log. | |
| 235 It should contain all details about connection and why it | |
| 236 failed. All related messages contain "quic " prefix and can | |
| 237 be easily filtered out. | |
| 238 | |
| 239 + If you want to investigate deeper, you may want to enable | |
| 240 additional debugging in src/event/ngx_event_quic.h: | |
| 241 | |
| 242 #define NGX_QUIC_DEBUG_PACKETS | |
| 243 #define NGX_QUIC_DEBUG_FRAMES | |
| 244 #define NGX_QUIC_DEBUG_FRAMES_ALLOC | |
| 245 #define NGX_QUIC_DEBUG_CRYPTO | |
| 246 | |
|
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
247 6. Contributing |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
248 |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
249 If you are willing to contribute, please refer to |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
250 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
|
251 |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
252 7. Links |
| 8366 | 253 |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
254 [1] https://tools.ietf.org/html/draft-ietf-quic-transport-29 |
|
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
255 [2] https://tools.ietf.org/html/draft-ietf-quic-http-29 |
| 8366 | 256 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel |
| 257 [4] https://boringssl.googlesource.com/boringssl/ | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
258 [5] https://tools.ietf.org/html/draft-ietf-quic-recovery-29 |
| 8366 | 259 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen |
| 260 [7] https://nginx.org/en/docs/debugging_log.html |