Mercurial > hg > nginx-quic
annotate README @ 7870:e169cce912c7 quic
Avoid retransmitting of packets with discarded keys.
Sections 4.10.1 and 4.10.2 of quic transport describe discarding of initial
and handshake keys. Since the keys are discarded, we no longer need
to retransmit packets and corresponding queues should be emptied.
This patch removes previously added workaround that did not require
acknowledgement for initial packets, resulting in avoiding retransmission,
which is wrong because a packet could be lost and we have to retransmit it.
| author | Vladimir Homutov <vl@nginx.com> |
|---|---|
| date | Mon, 18 May 2020 13:54:53 +0300 |
| parents | 70dbd7d0e466 |
| children | 578563babbd1 |
| rev | line source |
|---|---|
| 7843 | 1 Experimental QUIC support for nginx |
| 2 ----------------------------------- | |
| 3 | |
| 4 1. Introduction | |
| 5 2. Installing | |
| 6 3. Configuration | |
| 7 4. Clients | |
| 8 5. Troubleshooting | |
| 9 6. Links | |
| 10 | |
| 11 1. Introduction | |
| 12 | |
| 13 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx. | |
| 14 | |
| 15 The code is developed in a separate "quic" branch available | |
| 16 at https://hg.nginx.org/nginx-quic. Currently it is based | |
| 17 on nginx mainline 1.17.10. We are planning to merge new nginx | |
| 18 releases into this branch regularly. | |
| 19 | |
| 20 The project code base is under the same BSD license as nginx. | |
| 21 | |
| 22 The code is at an early alpha level of quality and should not | |
| 23 be used in production. | |
| 24 | |
| 25 We are working on improving HTTP/3 support with the goal of | |
| 26 integrating it to the main NGINX codebase. Expect frequent | |
| 27 updates of this code and don't rely on it for whatever purpose. | |
| 28 | |
| 29 We'll be grateful for any feedback and code submissions however | |
| 30 we don't bear any responsibilities for any issues with this code. | |
| 31 | |
| 32 You can always contact us via nginx-devel mailing list [3]. | |
| 33 | |
| 34 What works now: | |
| 35 | |
| 36 Currently we support IETF-QUIC draft 27 | |
| 37 Earlier drafts are NOT supported as they have incompatible wire format; | |
| 38 | |
| 39 nginx should be able to respond to simple HTTP/3 requests over QUIC and | |
| 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 | |
| 7867 | 44 + 0-RTT data is being received and acted on |
| 7843 | 45 + Connection is established using TLS Resume Ticket |
|
7866
2b580ac17a47
README: Retry support, protocol error messages implemented.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7850
diff
changeset
|
46 + A handshake that includes a Retry packet completes successfully |
| 7843 | 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 | |
| 51 | |
| 52 Not (yet) supported features: | |
| 53 | |
| 54 - Version negotiation | |
| 55 - ECN, Congestion control and friends as specified in quic-recovery [5] | |
| 56 - A connection with the spin bit succeeds and the bit is spinning | |
| 57 - Structured Logging | |
| 58 - QUIC recovery (proper congestion and flow control) | |
| 59 - NAT Rebinding | |
| 60 - Address Mobility | |
| 61 - Server push | |
| 62 - HTTP/3 trailers | |
| 63 | |
| 64 Since the code is experimental and still under development, | |
| 65 a lot of things may not work as expected, for example: | |
| 66 | |
| 67 - ACK handling is basic: every received ack-eliciting packet | |
| 68 is acknowledged, no ack ranges are used | |
| 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 | |
|
7850
796b5b6c43cd
Mention quic branch in README.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7849
diff
changeset
|
80 $ hg clone -b quic https://hg.nginx.org/nginx-quic |
| 7843 | 81 $ cd nginx-quic |
|
7849
0e6528551f26
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
Sergey Kandaurov <pluknet@nginx.com>
parents:
7843
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:
7843
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:
7843
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:
7843
diff
changeset
|
85 -L../boringssl/build/crypto" |
| 7843 | 86 $ make |
| 87 | |
| 88 3. Configuration | |
| 89 | |
| 90 The "listen" directive got a new option: "http3" | |
| 91 which enables HTTP/3 over QUIC on the specified port. | |
| 92 | |
| 93 Along with "http3", you also have to specify "reuseport" option [6] | |
| 94 to make it work properly with multiple workers. | |
| 95 | |
| 96 A number of directives were added that specify transport parameter values: | |
| 97 | |
| 98 quic_max_idle_timeout | |
| 99 quic_max_ack_delay | |
| 100 quic_max_packet_size | |
| 101 quic_initial_max_data | |
| 102 quic_initial_max_stream_data_bidi_local | |
| 103 quic_initial_max_stream_data_bidi_remote | |
| 104 quic_initial_max_stream_data_uni | |
| 105 quic_initial_max_streams_bidi | |
| 106 quic_initial_max_streams_uni | |
| 107 quic_ack_delay_exponent | |
| 108 quic_active_migration | |
| 109 quic_active_connection_id_limit | |
| 110 | |
| 111 Two additional variables are available: $quic and $http3. | |
| 112 The value of $quic is "quic" if QUIC connection is used, | |
| 113 and empty string otherwise. The value of $http3 is a string | |
| 114 "h3-xx" where "xx" is the supported draft number. | |
| 115 | |
| 116 Example configuration: | |
| 117 | |
| 118 http { | |
| 119 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
| 120 '"$request" $status $body_bytes_sent ' | |
| 121 '"$http_referer" "$http_user_agent" "$quic" "$http3"'; | |
| 122 | |
| 123 access_log logs/access.log quic; | |
| 124 | |
| 125 server { | |
| 126 # for better compatibility it's recommended | |
| 127 # to use the same port for quic and https | |
| 128 listen 8443 http3 reuseport; | |
| 129 listen 8443 ssl; | |
| 130 | |
| 131 ssl_certificate certs/example.com.crt; | |
| 132 ssl_certificate_key certs/example.com.key; | |
| 133 ssl_protocols TLSv1.3; | |
| 134 | |
| 135 location / { | |
| 136 # required for browsers to direct them into quic port | |
| 137 add_header Alt-Svc $http3=":8443"; | |
| 138 } | |
| 139 } | |
| 140 } | |
| 141 | |
| 142 4. Clients | |
| 143 | |
| 144 * Browsers | |
| 145 | |
| 146 Known to work: Firefox 75+ and Chrome 83+ | |
| 147 | |
| 148 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
| 149 Cache clearing/restart might help. Always check access.log and | |
| 150 error.log to make sure you are using HTTP/3 and not TCP https. | |
| 151 | |
| 152 + to enable QUIC in Firefox, set the following in 'about:config': | |
| 153 network.http.http3.enabled = true | |
| 154 | |
| 155 + to enable QUIC in Chrome, enable it on command line and force it | |
| 156 on your site: | |
| 157 | |
| 158 $ ./chrome --enable-quic --quic-version=h3-27 \ | |
| 159 --origin-to-force-quic-on=example.com:8443 | |
| 160 | |
| 161 * Console clients | |
| 162 | |
| 163 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
| 164 | |
| 165 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
| 166 | |
| 167 $ ./neqo-client https://127.0.0.1:8443/ | |
| 168 | |
| 169 $ chromium-build/out/my_build/quic_client http://example.com:8443 \ | |
| 170 --quic_version=h3-27 \ | |
| 171 --allow_unknown_root_cert \ | |
| 172 --disable_certificate_verification | |
| 173 | |
| 174 | |
| 175 If you've got it right, in the access log you should see something like: | |
| 176 | |
| 177 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" | |
| 178 "nghttp3/ngtcp2 client" "quic" "h3-27" | |
| 179 | |
| 180 | |
| 181 5. Troubleshooting | |
| 182 | |
| 183 Here are some tips that may help you to identify problems: | |
| 184 | |
| 185 + Ensure you are building with proper SSL library that | |
| 186 implements draft 27 | |
| 187 | |
| 188 + Ensure you are using the proper SSL library in runtime | |
| 189 (`nginx -V` will show you what you are using) | |
| 190 | |
| 191 + Ensure your client is actually sending QUIC requests | |
| 192 (see "Clients" section about browsers and cache) | |
| 193 | |
| 194 We recommend to start with simple console client like ngtcp2 | |
| 195 to ensure you've got server configured properly before trying | |
| 196 with real browsers that may be very peaky with certificates, | |
| 197 for example. | |
| 198 | |
| 199 + Build nginx with debug support [7] and check your debug log. | |
| 200 It should contain all details about connection and why it | |
| 201 failed. All related messages contain "quic " prefix and can | |
| 202 be easily filtered out. | |
| 203 | |
| 204 + If you want to investigate deeper, you may want to enable | |
| 205 additional debugging in src/event/ngx_event_quic.h: | |
| 206 | |
| 207 #define NGX_QUIC_DEBUG_PACKETS | |
| 208 #define NGX_QUIC_DEBUG_FRAMES | |
| 209 #define NGX_QUIC_DEBUG_FRAMES_ALLOC | |
| 210 #define NGX_QUIC_DEBUG_CRYPTO | |
| 211 | |
| 212 6. Links | |
| 213 | |
| 214 [1] https://tools.ietf.org/html/draft-ietf-quic-transport-27 | |
| 215 [2] https://tools.ietf.org/html/draft-ietf-quic-http-27 | |
| 216 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel | |
| 217 [4] https://boringssl.googlesource.com/boringssl/ | |
| 218 [5] https://tools.ietf.org/html/draft-ietf-quic-recovery-27 | |
| 219 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen | |
| 220 [7] https://nginx.org/en/docs/debugging_log.html |