Mercurial > hg > nginx
annotate README @ 8657:2dfc5ef29973 quic
QUIC: introduced QUIC buffers.
Buffers are used to hold frame data. They have a fixed size and are reused
after being freed.
| author | Roman Arutyunyan <arut@nginx.com> |
|---|---|
| date | Tue, 01 Dec 2020 19:11:01 +0000 |
| parents | dd8e50e11bfc |
| children | 27bd6dc24426 |
| 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 | |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
18 on nginx mainline 1.19.x. We merge new nginx releases into |
|
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
19 this branch regularly. |
| 8366 | 20 |
| 21 The project code base is under the same BSD license as nginx. | |
| 22 | |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
23 The code is currently at a beta level of quality and should not |
| 8366 | 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 | |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
37 Currently we support IETF-QUIC draft-27 through draft-32. |
|
8449
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 |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
43 nginx should be able to respond to HTTP/3 requests over QUIC and |
| 8366 | 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 - Flow control mechanism is basic and intended to avoid CPU hog and make | |
| 71 simple interactions possible | |
| 72 | |
| 73 - Not all draft requirements are strictly followed; some of checks are | |
| 74 omitted for the sake of simplicity of initial implementation | |
| 75 | |
| 76 2. Installing | |
| 77 | |
| 78 You will need a BoringSSL [4] library that provides QUIC support | |
| 79 | |
|
8373
796b5b6c43cd
Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8372
diff
changeset
|
80 $ hg clone -b quic https://hg.nginx.org/nginx-quic |
| 8366 | 81 $ cd nginx-quic |
|
8372
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8366
diff
changeset
|
82 $ ./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
|
83 --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
|
84 --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
|
85 -L../boringssl/build/crypto" |
| 8366 | 86 $ make |
| 87 | |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
88 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
|
89 following new configuration options: |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
90 |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
91 --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
|
92 --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
|
93 --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
|
94 |
| 8366 | 95 3. Configuration |
| 96 | |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
97 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
|
98 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
|
99 The "quic" option enables QUIC for older HTTP versions on this port. |
| 8366 | 100 |
|
8487
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
101 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
|
102 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
|
103 |
|
6e84524886d4
QUIC: updated README to mention "quic" listen parameter.
Roman Arutyunyan <arut@nginx.com>
parents:
8449
diff
changeset
|
104 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
|
105 option [6] to make it work properly with multiple workers. |
| 8366 | 106 |
| 107 A number of directives were added that specify transport parameter values: | |
| 108 | |
| 109 quic_max_idle_timeout | |
| 110 quic_max_ack_delay | |
| 111 quic_max_packet_size | |
| 112 quic_initial_max_data | |
| 113 quic_initial_max_stream_data_bidi_local | |
| 114 quic_initial_max_stream_data_bidi_remote | |
| 115 quic_initial_max_stream_data_uni | |
| 116 quic_initial_max_streams_bidi | |
| 117 quic_initial_max_streams_uni | |
| 118 quic_ack_delay_exponent | |
| 119 quic_active_migration | |
| 120 quic_active_connection_id_limit | |
| 121 | |
|
8402
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
122 To enable address validation: |
|
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 quic_retry on; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
125 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
126 To enable 0-RTT: |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
127 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
128 ssl_early_data on; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
129 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
130 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
|
131 |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
132 ssl_protocols TLSv1.3; |
|
af22b60a905b
README: documented Retry, 0-RTT, TLSv1.3 configuration.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8396
diff
changeset
|
133 |
|
8498
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
134 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
|
135 |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
136 http3_max_field_size |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
137 http3_max_table_capacity |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
138 http3_max_blocked_streams |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
139 http3_max_concurrent_pushes |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
140 http3_push |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
141 http3_push_preload |
|
affb0245e291
QUIC: added HTTP/3 directives list to README.
Roman Arutyunyan <arut@nginx.com>
parents:
8487
diff
changeset
|
142 |
| 8366 | 143 Two additional variables are available: $quic and $http3. |
| 144 The value of $quic is "quic" if QUIC connection is used, | |
| 145 and empty string otherwise. The value of $http3 is a string | |
| 146 "h3-xx" where "xx" is the supported draft number. | |
| 147 | |
| 148 Example configuration: | |
| 149 | |
| 150 http { | |
| 151 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
| 152 '"$request" $status $body_bytes_sent ' | |
| 153 '"$http_referer" "$http_user_agent" "$quic" "$http3"'; | |
| 154 | |
| 155 access_log logs/access.log quic; | |
| 156 | |
| 157 server { | |
| 158 # for better compatibility it's recommended | |
| 159 # to use the same port for quic and https | |
| 160 listen 8443 http3 reuseport; | |
| 161 listen 8443 ssl; | |
| 162 | |
| 163 ssl_certificate certs/example.com.crt; | |
| 164 ssl_certificate_key certs/example.com.key; | |
| 165 ssl_protocols TLSv1.3; | |
| 166 | |
| 167 location / { | |
| 168 # 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
|
169 add_header Alt-Svc '$http3=":8443"; ma=86400'; |
| 8366 | 170 } |
| 171 } | |
| 172 } | |
| 173 | |
| 174 4. Clients | |
| 175 | |
| 176 * Browsers | |
| 177 | |
| 178 Known to work: Firefox 75+ and Chrome 83+ | |
| 179 | |
| 180 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
| 181 Cache clearing/restart might help. Always check access.log and | |
| 182 error.log to make sure you are using HTTP/3 and not TCP https. | |
| 183 | |
| 184 + to enable QUIC in Firefox, set the following in 'about:config': | |
| 185 network.http.http3.enabled = true | |
| 186 | |
| 187 + to enable QUIC in Chrome, enable it on command line and force it | |
| 188 on your site: | |
| 189 | |
|
8547
57e5393e5d40
QUIC: switched to draft 29 by default.
Vladimir Homutov <vl@nginx.com>
parents:
8527
diff
changeset
|
190 $ ./chrome --enable-quic --quic-version=h3-29 \ |
| 8366 | 191 --origin-to-force-quic-on=example.com:8443 |
| 192 | |
| 193 * Console clients | |
| 194 | |
| 195 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
| 196 | |
| 197 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
| 198 | |
| 199 $ ./neqo-client https://127.0.0.1:8443/ | |
| 200 | |
| 201 $ 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
|
202 --quic_version=h3-29 \ |
| 8366 | 203 --allow_unknown_root_cert \ |
| 204 --disable_certificate_verification | |
| 205 | |
| 206 | |
| 207 If you've got it right, in the access log you should see something like: | |
| 208 | |
| 209 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
|
210 "nghttp3/ngtcp2 client" "quic" "h3-29" |
| 8366 | 211 |
| 212 | |
| 213 5. Troubleshooting | |
| 214 | |
| 215 Here are some tips that may help you to identify problems: | |
| 216 | |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
217 + Ensure you are building with proper SSL library that supports QUIC |
| 8366 | 218 |
| 219 + Ensure you are using the proper SSL library in runtime | |
| 220 (`nginx -V` will show you what you are using) | |
| 221 | |
| 222 + Ensure your client is actually sending QUIC requests | |
| 223 (see "Clients" section about browsers and cache) | |
| 224 | |
| 225 We recommend to start with simple console client like ngtcp2 | |
| 226 to ensure you've got server configured properly before trying | |
| 8395 | 227 with real browsers that may be very picky with certificates, |
| 8366 | 228 for example. |
| 229 | |
| 230 + Build nginx with debug support [7] and check your debug log. | |
| 231 It should contain all details about connection and why it | |
| 232 failed. All related messages contain "quic " prefix and can | |
| 233 be easily filtered out. | |
| 234 | |
| 235 + If you want to investigate deeper, you may want to enable | |
| 236 additional debugging in src/event/ngx_event_quic.h: | |
| 237 | |
| 238 #define NGX_QUIC_DEBUG_PACKETS | |
| 239 #define NGX_QUIC_DEBUG_FRAMES | |
|
8657
2dfc5ef29973
QUIC: introduced QUIC buffers.
Roman Arutyunyan <arut@nginx.com>
parents:
8601
diff
changeset
|
240 #define NGX_QUIC_DEBUG_ALLOC |
| 8366 | 241 #define NGX_QUIC_DEBUG_CRYPTO |
| 242 | |
|
8410
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
243 6. Contributing |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
244 |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
245 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
|
246 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
|
247 |
|
c7d1b500bd0a
Updated README with "Contributing" section and draft details.
Vladimir Homutov <vl@nginx.com>
parents:
8402
diff
changeset
|
248 7. Links |
| 8366 | 249 |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
250 [1] https://tools.ietf.org/html/draft-ietf-quic-transport |
|
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
251 [2] https://tools.ietf.org/html/draft-ietf-quic-http |
| 8366 | 252 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel |
| 253 [4] https://boringssl.googlesource.com/boringssl/ | |
|
8601
dd8e50e11bfc
QUIC: updated README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
8547
diff
changeset
|
254 [5] https://tools.ietf.org/html/draft-ietf-quic-recovery |
| 8366 | 255 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen |
| 256 [7] https://nginx.org/en/docs/debugging_log.html |