Hello! On Sun, May 14, 2023 at 05:38:55PM +0400, Roman Arutyunyan wrote:
> # HG changeset patch > # User Roman Arutyunyan <a...@nginx.com> > # Date 1684045884 -14400 > # Sun May 14 10:31:24 2023 +0400 > # Branch quic > # Node ID d8272b84031bea1940ef8a5b8e2f79ec6a2dcfc1 > # Parent 49a8edf7bf31b78681399cd7e93a8516788607dd > Removed README. > > diff --git a/README b/README > deleted file mode 100644 > --- 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 <filename>; > - > - 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 Looks good. -- Maxim Dounin http://mdounin.ru/ _______________________________________________ nginx-devel mailing list nginx-devel@nginx.org https://mailman.nginx.org/mailman/listinfo/nginx-devel
