diff --git a/README b/README deleted file mode 100644 index 7bb7f14fb..000000000 --- a/README +++ /dev/null @@ -1,319 +0,0 @@ -Experimental QUIC support for nginx ------------------------------------ - -1. Introduction -2. Building from sources -3. Configuration -4. Directives -5. Clients -6. Troubleshooting -7. Contributing -8. 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.23.x. We merge new nginx releases into - this branch regularly. - - The project code base is under the same BSD license as nginx. - - The code is currently at a beta level of quality, however - there are several production deployments with it. - - NGINX Development Team is working on improving HTTP/3 support to - integrate it into the main NGINX codebase. Thus, expect further - updates of this code, including features, changes in behaviour, - bug fixes, and refactoring. NGINX Development team will be - grateful for any feedback and code submissions. - - Please contact NGINX Development Team via nginx-devel mailing list [3]. - - What works now: - - IETF QUIC version 1 is supported. Internet drafts are no longer supported. - - nginx should be able to respond to 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 - + Version Negotiation packet is sent to client with unknown version - + Lost packets are detected and retransmitted properly - + Clients may migrate to new address - -2. Building from sources - - The build is configured using the configure command. - Refer to http://nginx.org/en/docs/configure.html for details. - - When configuring nginx, it's possible to enable QUIC and HTTP/3 - using the following new configuration option: - - --with-http_v3_module - enable QUIC and HTTP/3 - - A library that provides QUIC support is recommended to build nginx, there - are several of those available on the market: - + BoringSSL [4] - + LibreSSL [5] - + QuicTLS [6] - - Alternatively, nginx can be configured with OpenSSL compatibility - layer, which emulates BoringSSL QUIC API for OpenSSL. This mode is - enabled by default if native QUIC support is not detected. - 0-RTT is not supported in OpenSSL compatibility mode. - - Clone the NGINX QUIC repository - - $ hg clone -b quic https://hg.nginx.org/nginx-quic - $ cd nginx-quic - - Use the following command to configure nginx with BoringSSL [4] - - $ ./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 - - Alternatively, nginx can be configured with QuicTLS [6] - - $ ./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../quictls/build/include" \ - --with-ld-opt="-L../quictls/build/lib" - - Alternatively, nginx can be configured with a modern version - of LibreSSL [7] - - $ ./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../libressl/build/include" \ - --with-ld-opt="-L../libressl/build/lib" - -3. Configuration - - The HTTP "listen" directive got a new option "quic" which enables - QUIC as client transport protocol instead of TCP. - - Along with "quic", it's also possible to specify "reuseport" - option [8] to make it work properly with multiple workers. - - To enable address validation: - - quic_retry on; - - To enable 0-RTT: - - ssl_early_data on; - - To enable GSO (Generic Segmentation Offloading): - - quic_gso on; - - To set host key for various tokens: - - quic_host_key ; - - QUIC requires TLSv1.3 protocol, which is enabled by the default - by "ssl_protocols" directive. - - By default, GSO Linux-specific optimization [10] is disabled. - Enable it in case a corresponding network interface is configured to - support GSO. - - A number of directives were added that configure HTTP/3: - - http3 - http3_hq - http3_stream_buffer_size - http3_max_concurrent_streams - - In http, an additional variable is available: $http3. - The value of $http3 is "h3" for HTTP/3 connections, - "hq" for hq connections, or an empty string otherwise. - -Example configuration: - - http { - log_format quic '$remote_addr - $remote_user [$time_local] ' - '"$request" $status $body_bytes_sent ' - '"$http_referer" "$http_user_agent" "$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 quic reuseport; - listen 8443 ssl; - - ssl_certificate certs/example.com.crt; - ssl_certificate_key certs/example.com.key; - - location / { - # required for browsers to direct them into quic port - add_header Alt-Svc 'h3=":8443"; ma=86400'; - } - } - } - -4. Directives - - Syntax: quic_bpf on | off; - Default: quic_bpf off; - Context: main - - Enables routing of QUIC packets using eBPF. - When enabled, this allows to support QUIC connection migration. - The directive is only supported on Linux 5.7+. - - - Syntax: quic_retry on | off; - Default: quic_retry off; - Context: http, server - - Enables the QUIC Address Validation feature. This includes: - - sending a new token in a Retry packet or a NEW_TOKEN frame - - validating a token received in the Initial packet - - - Syntax: quic_gso on | off; - Default: quic_gso off; - Context: http, server - - Enables sending in optimized batch mode using segmentation offloading. - Optimized sending is only supported on Linux featuring UDP_SEGMENT. - - - Syntax: quic_host_key file; - Default: - - Context: http, server - - Specifies a file with the secret key used to encrypt stateless reset and - address validation tokens. By default, a randomly generated key is used. - - - Syntax: quic_active_connection_id_limit number; - Default: quic_active_connection_id_limit 2; - Context: http, server - - Sets the QUIC active_connection_id_limit transport parameter value. - This is the maximum number of connection IDs we are willing to store. - - - Syntax: http3_stream_buffer_size size; - Default: http3_stream_buffer_size 64k; - Context: http, server - - Sets buffer size for reading and writing of the QUIC STREAM payload. - The buffer size is used to calculate initial flow control limits - in the following QUIC transport parameters: - - initial_max_data - - initial_max_stream_data_bidi_local - - initial_max_stream_data_bidi_remote - - initial_max_stream_data_uni - - - Syntax: http3_max_concurrent_streams number; - Default: http3_max_concurrent_streams 128; - Context: http, server - - Sets the maximum number of concurrent HTTP/3 streams in a connection. - - - Syntax: http3 on | off; - Default: http3 on; - Context: http, server - - Enables HTTP/3 protocol negotiation. - - - Syntax: http3_hq on | off; - Default: http3_hq off; - Context: http, server - - Enables HTTP/0.9 protocol negotiation used in QUIC interoperability tests. - -5. Clients - - * Browsers - - Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1) - - 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 the browser is using HTTP/3 and not TCP https. - - * 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 - - - In case everyhing is right, the access log should show something like: - - 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-" - "nghttp3/ngtcp2 client" "quic" - - -6. Troubleshooting - - Here are some tips that may help to identify problems: - - + Ensure nginx is built with proper SSL library that supports QUIC - - + Ensure nginx is using the proper SSL library in runtime - (`nginx -V` shows what it's using) - - + Ensure a client is actually sending requests over QUIC - (see "Clients" section about browsers and cache) - - We recommend to start with simple console client like ngtcp2 - to ensure the server is configured properly before trying - with real browsers that may be very picky with certificates, - for example. - - + Build nginx with debug support [9] and check the 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. - - + For a deeper investigation, please enable additional debugging - in src/event/quic/ngx_event_quic_connection.h: - - #define NGX_QUIC_DEBUG_PACKETS - #define NGX_QUIC_DEBUG_FRAMES - #define NGX_QUIC_DEBUG_ALLOC - #define NGX_QUIC_DEBUG_CRYPTO - -7. Contributing - - Please refer to - http://nginx.org/en/docs/contributing_changes.html - -8. Links - - [1] https://datatracker.ietf.org/doc/html/rfc9000 - [2] https://datatracker.ietf.org/doc/html/rfc9114 - [3] https://mailman.nginx.org/mailman/listinfo/nginx-devel - [4] https://boringssl.googlesource.com/boringssl/ - [5] https://www.libressl.org/ - [6] https://github.com/quictls/openssl - [7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0 - [8] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen - [9] https://nginx.org/en/docs/debugging_log.html - [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf