mirror of
https://github.com/nginx/nginx.git
synced 2024-12-12 02:09:04 +08:00
The official NGINX Open Source repository.
a4e06606c5
This field is served as a simple counter for PTO backoff. |
||
---|---|---|
auto | ||
conf | ||
contrib | ||
docs | ||
misc | ||
src | ||
.hgtags | ||
README |
Experimental QUIC support for nginx ----------------------------------- 1. Introduction 2. Installing 3. Configuration 4. Clients 5. Troubleshooting 6. Contributing 7. Links 1. Introduction This is an experimental QUIC [1] / HTTP/3 [2] support for nginx. The code is developed in a separate "quic" branch available at https://hg.nginx.org/nginx-quic. Currently it is based on nginx mainline 1.19.x. We are planning to merge new nginx releases into this branch regularly. The project code base is under the same BSD license as nginx. The code is at an early alpha level of quality and should not be used in production. We are working on improving HTTP/3 support with the goal of integrating it to the main NGINX codebase. Expect frequent updates of this code and don't rely on it for whatever purpose. We'll be grateful for any feedback and code submissions however we don't bear any responsibilities for any issues with this code. You can always contact us via nginx-devel mailing list [3]. What works now: Currently we support IETF-QUIC draft-27, draft-28, draft-29. Earlier drafts are NOT supported as they have incompatible wire format. You may look at src/event/ngx_event_quic.h for alternative values of the NGX_QUIC_DRAFT_VERSION macro used to select IETF draft version number. nginx should be able to respond to simple HTTP/3 requests over QUIC and it should be possible to upload and download big files without errors. + The handshake completes successfully + One endpoint can update keys and its peer responds correctly + 0-RTT data is being received and acted on + Connection is established using TLS Resume Ticket + A handshake that includes a Retry packet completes successfully + Stream data is being exchanged and ACK'ed + An H3 transaction succeeded + One or both endpoints insert entries into dynamic table and subsequently reference them from header blocks Not (yet) supported features: - Version negotiation - ECN, Congestion control and friends as specified in quic-recovery [5] - A connection with the spin bit succeeds and the bit is spinning - Structured Logging - QUIC recovery (proper congestion and flow control) - NAT Rebinding - Address Mobility - HTTP/3 trailers Since the code is experimental and still under development, a lot of things may not work as expected, for example: - ACK handling is basic: every received ack-eliciting packet is acknowledged, no ack ranges are used - Flow control mechanism is basic and intended to avoid CPU hog and make simple interactions possible - Not all draft requirements are strictly followed; some of checks are omitted for the sake of simplicity of initial implementation 2. Installing You will need a BoringSSL [4] library that provides QUIC support $ hg clone -b quic https://hg.nginx.org/nginx-quic $ cd nginx-quic $ ./auto/configure --with-debug --with-http_v3_module \ --with-cc-opt="-I../boringssl/include" \ --with-ld-opt="-L../boringssl/build/ssl \ -L../boringssl/build/crypto" $ make When configuring nginx, you can enable QUIC and HTTP/3 using the following new configuration options: --with-http_v3_module - enable QUIC and HTTP/3 --with-http_quic_module - enable QUIC for older HTTP versions --with-stream_quic_module - enable QUIC in Stream 3. Configuration The HTTP "listen" directive got two new options: "http3" and "quic". The "http3" option enables HTTP/3 over QUIC on the specified port. The "quic" option enables QUIC for older HTTP versions on this port. The Stream "listen" directive got a new option "quic" which enables QUIC as client transport protocol instead of TCP or plain UDP. Along with "http3" or "quic", you also have to specify "reuseport" option [6] to make it work properly with multiple workers. A number of directives were added that specify transport parameter values: quic_max_idle_timeout quic_max_ack_delay quic_max_packet_size quic_initial_max_data quic_initial_max_stream_data_bidi_local quic_initial_max_stream_data_bidi_remote quic_initial_max_stream_data_uni quic_initial_max_streams_bidi quic_initial_max_streams_uni quic_ack_delay_exponent quic_active_migration quic_active_connection_id_limit To enable address validation: quic_retry on; To enable 0-RTT: ssl_early_data on; Make sure that TLS 1.3 is configured which is required for QUIC: ssl_protocols TLSv1.3; A number of directives were added that configure HTTP/3: http3_max_field_size http3_max_table_capacity http3_max_blocked_streams http3_max_concurrent_pushes http3_push http3_push_preload Two additional variables are available: $quic and $http3. The value of $quic is "quic" if QUIC connection is used, and empty string otherwise. The value of $http3 is a string "h3-xx" where "xx" is the supported draft number. Example configuration: http { log_format quic '$remote_addr - $remote_user [$time_local] ' '"$request" $status $body_bytes_sent ' '"$http_referer" "$http_user_agent" "$quic" "$http3"'; access_log logs/access.log quic; server { # for better compatibility it's recommended # to use the same port for quic and https listen 8443 http3 reuseport; listen 8443 ssl; ssl_certificate certs/example.com.crt; ssl_certificate_key certs/example.com.key; ssl_protocols TLSv1.3; location / { # required for browsers to direct them into quic port add_header Alt-Svc '$http3=":8443"; ma=86400'; } } } 4. Clients * Browsers Known to work: Firefox 75+ and Chrome 83+ Beware of strange issues: sometimes browser may decide to ignore QUIC Cache clearing/restart might help. Always check access.log and error.log to make sure you are using HTTP/3 and not TCP https. + to enable QUIC in Firefox, set the following in 'about:config': network.http.http3.enabled = true + to enable QUIC in Chrome, enable it on command line and force it on your site: $ ./chrome --enable-quic --quic-version=h3-27 \ --origin-to-force-quic-on=example.com:8443 * Console clients Known to work: ngtcp2, firefox's neqo and chromium's console clients: $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html $ ./neqo-client https://127.0.0.1:8443/ $ chromium-build/out/my_build/quic_client http://example.com:8443 \ --quic_version=h3-27 \ --allow_unknown_root_cert \ --disable_certificate_verification If you've got it right, in the access log you should see something like: 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" "nghttp3/ngtcp2 client" "quic" "h3-27" 5. Troubleshooting Here are some tips that may help you to identify problems: + Ensure you are building with proper SSL library that implements draft 27 + Ensure you are using the proper SSL library in runtime (`nginx -V` will show you what you are using) + Ensure your client is actually sending QUIC requests (see "Clients" section about browsers and cache) We recommend to start with simple console client like ngtcp2 to ensure you've got server configured properly before trying with real browsers that may be very picky with certificates, for example. + Build nginx with debug support [7] and check your debug log. It should contain all details about connection and why it failed. All related messages contain "quic " prefix and can be easily filtered out. + If you want to investigate deeper, you may want to enable additional debugging in src/event/ngx_event_quic.h: #define NGX_QUIC_DEBUG_PACKETS #define NGX_QUIC_DEBUG_FRAMES #define NGX_QUIC_DEBUG_FRAMES_ALLOC #define NGX_QUIC_DEBUG_CRYPTO 6. Contributing If you are willing to contribute, please refer to http://nginx.org/en/docs/contributing_changes.html 7. Links [1] https://tools.ietf.org/html/draft-ietf-quic-transport-27 [2] https://tools.ietf.org/html/draft-ietf-quic-http-27 [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel [4] https://boringssl.googlesource.com/boringssl/ [5] https://tools.ietf.org/html/draft-ietf-quic-recovery-27 [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen [7] https://nginx.org/en/docs/debugging_log.html