Mercurial > hg > nginx
annotate README @ 8372:0e6528551f26 quic
Configure: unbreak with old OpenSSL, --with-http_v3_module added.
| author | Sergey Kandaurov <pluknet@nginx.com> |
|---|---|
| date | Thu, 30 Apr 2020 15:47:43 +0300 |
| parents | 3e894ace66ee |
| children | 796b5b6c43cd |
| 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 | |
| 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 | |
| 44 + 00-RTT data is being received and acted on | |
| 45 + Connection is established using TLS Resume Ticket | |
| 46 + Stream data is being exchanged and ACK'ed | |
| 47 + An H3 transaction succeeded | |
| 48 + One or both endpoints insert entries into dynamic table and | |
| 49 subsequently reference them from header blocks | |
| 50 | |
| 51 Not (yet) supported features: | |
| 52 | |
| 53 - Version negotiation | |
| 54 - Stateless Retry | |
| 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 - Protocol error messages are not implemented, in case of error connection | |
| 68 closes silently for peer | |
| 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 | |
| 83 $ hg clone https://hg.nginx.org/nginx-quic | |
| 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 | |
| 91 3. Configuration | |
| 92 | |
| 93 The "listen" directive got a new option: "http3" | |
| 94 which enables HTTP/3 over QUIC on the specified port. | |
| 95 | |
| 96 Along with "http3", you also have to specify "reuseport" option [6] | |
| 97 to make it work properly with multiple workers. | |
| 98 | |
| 99 A number of directives were added that specify transport parameter values: | |
| 100 | |
| 101 quic_max_idle_timeout | |
| 102 quic_max_ack_delay | |
| 103 quic_max_packet_size | |
| 104 quic_initial_max_data | |
| 105 quic_initial_max_stream_data_bidi_local | |
| 106 quic_initial_max_stream_data_bidi_remote | |
| 107 quic_initial_max_stream_data_uni | |
| 108 quic_initial_max_streams_bidi | |
| 109 quic_initial_max_streams_uni | |
| 110 quic_ack_delay_exponent | |
| 111 quic_active_migration | |
| 112 quic_active_connection_id_limit | |
| 113 | |
| 114 Two additional variables are available: $quic and $http3. | |
| 115 The value of $quic is "quic" if QUIC connection is used, | |
| 116 and empty string otherwise. The value of $http3 is a string | |
| 117 "h3-xx" where "xx" is the supported draft number. | |
| 118 | |
| 119 Example configuration: | |
| 120 | |
| 121 http { | |
| 122 log_format quic '$remote_addr - $remote_user [$time_local] ' | |
| 123 '"$request" $status $body_bytes_sent ' | |
| 124 '"$http_referer" "$http_user_agent" "$quic" "$http3"'; | |
| 125 | |
| 126 access_log logs/access.log quic; | |
| 127 | |
| 128 server { | |
| 129 # for better compatibility it's recommended | |
| 130 # to use the same port for quic and https | |
| 131 listen 8443 http3 reuseport; | |
| 132 listen 8443 ssl; | |
| 133 | |
| 134 ssl_certificate certs/example.com.crt; | |
| 135 ssl_certificate_key certs/example.com.key; | |
| 136 ssl_protocols TLSv1.3; | |
| 137 | |
| 138 location / { | |
| 139 # required for browsers to direct them into quic port | |
| 140 add_header Alt-Svc $http3=":8443"; | |
| 141 } | |
| 142 } | |
| 143 } | |
| 144 | |
| 145 4. Clients | |
| 146 | |
| 147 * Browsers | |
| 148 | |
| 149 Known to work: Firefox 75+ and Chrome 83+ | |
| 150 | |
| 151 Beware of strange issues: sometimes browser may decide to ignore QUIC | |
| 152 Cache clearing/restart might help. Always check access.log and | |
| 153 error.log to make sure you are using HTTP/3 and not TCP https. | |
| 154 | |
| 155 + to enable QUIC in Firefox, set the following in 'about:config': | |
| 156 network.http.http3.enabled = true | |
| 157 | |
| 158 + to enable QUIC in Chrome, enable it on command line and force it | |
| 159 on your site: | |
| 160 | |
| 161 $ ./chrome --enable-quic --quic-version=h3-27 \ | |
| 162 --origin-to-force-quic-on=example.com:8443 | |
| 163 | |
| 164 * Console clients | |
| 165 | |
| 166 Known to work: ngtcp2, firefox's neqo and chromium's console clients: | |
| 167 | |
| 168 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html | |
| 169 | |
| 170 $ ./neqo-client https://127.0.0.1:8443/ | |
| 171 | |
| 172 $ chromium-build/out/my_build/quic_client http://example.com:8443 \ | |
| 173 --quic_version=h3-27 \ | |
| 174 --allow_unknown_root_cert \ | |
| 175 --disable_certificate_verification | |
| 176 | |
| 177 | |
| 178 If you've got it right, in the access log you should see something like: | |
| 179 | |
| 180 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" | |
| 181 "nghttp3/ngtcp2 client" "quic" "h3-27" | |
| 182 | |
| 183 | |
| 184 5. Troubleshooting | |
| 185 | |
| 186 Here are some tips that may help you to identify problems: | |
| 187 | |
| 188 + Ensure you are building with proper SSL library that | |
| 189 implements draft 27 | |
| 190 | |
| 191 + Ensure you are using the proper SSL library in runtime | |
| 192 (`nginx -V` will show you what you are using) | |
| 193 | |
| 194 + Ensure your client is actually sending QUIC requests | |
| 195 (see "Clients" section about browsers and cache) | |
| 196 | |
| 197 We recommend to start with simple console client like ngtcp2 | |
| 198 to ensure you've got server configured properly before trying | |
| 199 with real browsers that may be very peaky with certificates, | |
| 200 for example. | |
| 201 | |
| 202 + Build nginx with debug support [7] and check your debug log. | |
| 203 It should contain all details about connection and why it | |
| 204 failed. All related messages contain "quic " prefix and can | |
| 205 be easily filtered out. | |
| 206 | |
| 207 + If you want to investigate deeper, you may want to enable | |
| 208 additional debugging in src/event/ngx_event_quic.h: | |
| 209 | |
| 210 #define NGX_QUIC_DEBUG_PACKETS | |
| 211 #define NGX_QUIC_DEBUG_FRAMES | |
| 212 #define NGX_QUIC_DEBUG_FRAMES_ALLOC | |
| 213 #define NGX_QUIC_DEBUG_CRYPTO | |
| 214 | |
| 215 6. Links | |
| 216 | |
| 217 [1] https://tools.ietf.org/html/draft-ietf-quic-transport-27 | |
| 218 [2] https://tools.ietf.org/html/draft-ietf-quic-http-27 | |
| 219 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel | |
| 220 [4] https://boringssl.googlesource.com/boringssl/ | |
| 221 [5] https://tools.ietf.org/html/draft-ietf-quic-recovery-27 | |
| 222 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen | |
| 223 [7] https://nginx.org/en/docs/debugging_log.html |