nginx: README annotate

annotate README @ 9045:c6580dce98a8 quic

QUIC: fixed triggering stream read event (ticket #2409). If a client packet carrying a stream data frame is not acked due to packet loss, the stream data is retransmitted later by client. It's also possible that the retransmitted range is bigger than before due to more stream data being available by then. If the original data was read out by the application, there would be no read event triggered by the retransmitted frame, even though it contains new data.

author	Roman Arutyunyan <arut@nginx.com>
date	Wed, 23 Nov 2022 18:50:26 +0400
parents	79cd6993a3e3
children	3c33d39a51d3

rev	line source
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	1 Experimental QUIC support for nginx
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	2 -----------------------------------
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	3
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	4 1. Introduction
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	5 2. Installing
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	6 3. Configuration
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	7 4. Clients
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	8 5. Troubleshooting
8410 c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	9 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	10 7. Links
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	11
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	12 1. Introduction
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	13
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	14 This is an experimental QUIC [1] / HTTP/3 [2] support for nginx.
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	15
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	16 The code is developed in a separate "quic" branch available
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	17 at https://hg.nginx.org/nginx-quic. Currently it is based
9021 8d0753760546 Merged with the default branch. Sergey Kandaurov <pluknet@nginx.com> parents: 9019 diff changeset	18 on nginx mainline 1.23.x. We merge new nginx releases into
8601 dd8e50e11bfc QUIC: updated README. Sergey Kandaurov <pluknet@nginx.com> parents: 8547 diff changeset	19 this branch regularly.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	20
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	21 The project code base is under the same BSD license as nginx.
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	22
9028 98e94553ae51 README: updated the current status. Sergey Kandaurov <pluknet@nginx.com> parents: 9021 diff changeset	23 The code is currently at a beta level of quality, however
98e94553ae51 README: updated the current status. Sergey Kandaurov <pluknet@nginx.com> parents: 9021 diff changeset	24 there are several production deployments with it.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	25
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	26 NGINX Development Team is working on improving HTTP/3 support to
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	27 integrate it into the main NGINX codebase. Thus, expect further
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	28 updates of this code, including features, changes in behaviour,
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	29 bug fixes, and refactoring. NGINX Development team will be
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	30 grateful for any feedback and code submissions.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	31
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	32 Please contact NGINX Development Team via nginx-devel mailing list [3].
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	33
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	34 What works now:
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	35
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	36 IETF QUIC version 1 is supported. Internet drafts are no longer supported.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	37
8601 dd8e50e11bfc QUIC: updated README. Sergey Kandaurov <pluknet@nginx.com> parents: 8547 diff changeset	38 nginx should be able to respond to HTTP/3 requests over QUIC and
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	39 it should be possible to upload and download big files without errors.
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	40
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	41 + The handshake completes successfully
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	42 + One endpoint can update keys and its peer responds correctly
8390 70dbd7d0e466 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 8389 diff changeset	43 + 0-RTT data is being received and acted on
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	44 + Connection is established using TLS Resume Ticket
8389 2b580ac17a47 README: Retry support, protocol error messages implemented. Sergey Kandaurov <pluknet@nginx.com> parents: 8373 diff changeset	45 + A handshake that includes a Retry packet completes successfully
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	46 + Stream data is being exchanged and ACK'ed
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	47 + An H3 transaction succeeded
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	48 + One or both endpoints insert entries into dynamic table and
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	49 subsequently reference them from header blocks
8527 cec7f207a4bf QUIC: updated README. Vladimir Homutov <vl@nginx.com> parents: 8498 diff changeset	50 + Version Negotiation packet is sent to client with unknown version
cec7f207a4bf QUIC: updated README. Vladimir Homutov <vl@nginx.com> parents: 8498 diff changeset	51 + Lost packets are detected and retransmitted properly
8763 4117aa7fa38e QUIC: connection migration. Vladimir Homutov <vl@nginx.com> parents: 8747 diff changeset	52 + Clients may migrate to new address
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	53
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	54 2. Installing
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	55
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	56 A library that provides QUIC support is required to build nginx, there
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	57 are several of those available on the market:
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	58 + BoringSSL [4]
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	59 + LibreSSL [5]
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	60 + QuicTLS [6]
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	61
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	62 Clone the NGINX QUIC repository
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	63
8373 796b5b6c43cd Mention quic branch in README. Sergey Kandaurov <pluknet@nginx.com> parents: 8372 diff changeset	64 $ hg clone -b quic https://hg.nginx.org/nginx-quic
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	65 $ cd nginx-quic
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	66
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	67 Use the following command to configure nginx with BoringSSL [4]
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	68
8966 6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	69 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	70 --with-cc-opt="-I../boringssl/include" \
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	71 --with-ld-opt="-L../boringssl/build/ssl \
8372 0e6528551f26 Configure: unbreak with old OpenSSL, --with-http_v3_module added. Sergey Kandaurov <pluknet@nginx.com> parents: 8366 diff changeset	72 -L../boringssl/build/crypto"
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	73 $ make
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	74
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	75 Alternatively, nginx can be configured with QuicTLS [6]
8966 6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	76
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	77 $ ./auto/configure --with-debug --with-http_v3_module \
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	78 --with-cc-opt="-I../quictls/build/include" \
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	79 --with-ld-opt="-L../quictls/build/lib"
6f8253673669 README: documented QuicTLS support. Sergey Kandaurov <pluknet@nginx.com> parents: 8929 diff changeset	80
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	81 Alternatively, nginx can be configured with a modern version
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	82 of LibreSSL [7]
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	83
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	84 $ ./auto/configure --with-debug --with-http_v3_module \
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	85 --with-cc-opt="-I../libressl/build/include" \
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	86 --with-ld-opt="-L../libressl/build/lib"
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	87
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	88 When configuring nginx, it's possible to enable QUIC and HTTP/3
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	89 using the following new configuration options:
8487 6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	90
6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	91 --with-http_v3_module - enable QUIC and HTTP/3
6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	92 --with-stream_quic_module - enable QUIC in Stream
6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	93
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	94 3. Configuration
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	95
8922 be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro. Roman Arutyunyan <arut@nginx.com> parents: 8840 diff changeset	96 The HTTP "listen" directive got a new option "http3" which enables
be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro. Roman Arutyunyan <arut@nginx.com> parents: 8840 diff changeset	97 HTTP/3 over QUIC on the specified port.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	98
8487 6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	99 The Stream "listen" directive got a new option "quic" which enables
6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	100 QUIC as client transport protocol instead of TCP or plain UDP.
6e84524886d4 QUIC: updated README to mention "quic" listen parameter. Roman Arutyunyan <arut@nginx.com> parents: 8449 diff changeset	101
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	102 Along with "http3" or "quic", it's also possible to specify "reuseport"
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	103 option [8] to make it work properly with multiple workers.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	104
8402 af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	105 To enable address validation:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	106
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	107 quic_retry on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	108
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	109 To enable 0-RTT:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	110
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	111 ssl_early_data on;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	112
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	113 Make sure that TLS 1.3 is configured which is required for QUIC:
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	114
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	115 ssl_protocols TLSv1.3;
af22b60a905b README: documented Retry, 0-RTT, TLSv1.3 configuration. Sergey Kandaurov <pluknet@nginx.com> parents: 8396 diff changeset	116
8819 d0ef43a53a51 QUIC: updated README with GSO details. Vladimir Homutov <vl@nginx.com> parents: 8804 diff changeset	117 To enable GSO (Generic Segmentation Offloading):
d0ef43a53a51 QUIC: updated README with GSO details. Vladimir Homutov <vl@nginx.com> parents: 8804 diff changeset	118
d0ef43a53a51 QUIC: updated README with GSO details. Vladimir Homutov <vl@nginx.com> parents: 8804 diff changeset	119 quic_gso on;
d0ef43a53a51 QUIC: updated README with GSO details. Vladimir Homutov <vl@nginx.com> parents: 8804 diff changeset	120
9019 0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements. Sergey Kandaurov <pluknet@nginx.com> parents: 8984 diff changeset	121 To limit maximum UDP payload size on receive path:
8924 d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	122
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	123 quic_mtu <size>;
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	124
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	125 To set host key for various tokens:
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	126
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	127 quic_host_key <filename>;
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	128
d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	129
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	130 By default, GSO Linux-specific optimization [10] is disabled.
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	131 Enable it in case a corresponding network interface is configured to
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	132 support GSO.
8819 d0ef43a53a51 QUIC: updated README with GSO details. Vladimir Homutov <vl@nginx.com> parents: 8804 diff changeset	133
8498 affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	134 A number of directives were added that configure HTTP/3:
affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	135
8924 d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	136 http3_stream_buffer_size
8498 affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	137 http3_max_concurrent_pushes
8924 d6ef13c5fd8e QUIC: simplified configuration. Vladimir Homutov <vl@nginx.com> parents: 8923 diff changeset	138 http3_max_concurrent_streams
8498 affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	139 http3_push
affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	140 http3_push_preload
8922 be08b858086a HTTP/3: http3_hq directive and NGX_HTTP_V3_HQ macro. Roman Arutyunyan <arut@nginx.com> parents: 8840 diff changeset	141 http3_hq (requires NGX_HTTP_V3_HQ macro)
8498 affb0245e291 QUIC: added HTTP/3 directives list to README. Roman Arutyunyan <arut@nginx.com> parents: 8487 diff changeset	142
8923 651cc905b7c2 HTTP/3: $http3 variable. Roman Arutyunyan <arut@nginx.com> parents: 8922 diff changeset	143 In http, an additional variable is available: $http3.
651cc905b7c2 HTTP/3: $http3 variable. Roman Arutyunyan <arut@nginx.com> parents: 8922 diff changeset	144 The value of $http3 is "h3" for HTTP/3 connections,
651cc905b7c2 HTTP/3: $http3 variable. Roman Arutyunyan <arut@nginx.com> parents: 8922 diff changeset	145 "hq" for hq connections, or an empty string otherwise.
651cc905b7c2 HTTP/3: $http3 variable. Roman Arutyunyan <arut@nginx.com> parents: 8922 diff changeset	146
651cc905b7c2 HTTP/3: $http3 variable. Roman Arutyunyan <arut@nginx.com> parents: 8922 diff changeset	147 In stream, an additional variable is available: $quic.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	148 The value of $quic is "quic" if QUIC connection is used,
8788 f0882db8c8d4 HTTP/3: removed $http3 that served its purpose. Sergey Kandaurov <pluknet@nginx.com> parents: 8787 diff changeset	149 or an empty string otherwise.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	150
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	151 Example configuration:
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	152
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	153 http {
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	154 log_format quic '$remote_addr - $remote_user [$time_local] '
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	155 '"$request" $status $body_bytes_sent '
8929 44553428288d QUIC: updated README. Vladimir Homutov <vl@nginx.com> parents: 8924 diff changeset	156 '"$http_referer" "$http_user_agent" "$http3"';
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	157
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	158 access_log logs/access.log quic;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	159
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	160 server {
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	161 # for better compatibility it's recommended
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	162 # to use the same port for quic and https
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	163 listen 8443 http3 reuseport;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	164 listen 8443 ssl;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	165
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	166 ssl_certificate certs/example.com.crt;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	167 ssl_certificate_key certs/example.com.key;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	168 ssl_protocols TLSv1.3;
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	169
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	170 location / {
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	171 # required for browsers to direct them into quic port
8788 f0882db8c8d4 HTTP/3: removed $http3 that served its purpose. Sergey Kandaurov <pluknet@nginx.com> parents: 8787 diff changeset	172 add_header Alt-Svc 'h3=":8443"; ma=86400';
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	173 }
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	174 }
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	175 }
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	176
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	177 4. Clients
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	178
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	179 * Browsers
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	180
8982 8f5d0ade0da7 README: updated to QUICv1. Sergey Kandaurov <pluknet@nginx.com> parents: 8966 diff changeset	181 Known to work: Firefox 90+ and Chrome 92+ (QUIC version 1)
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	182
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	183 Beware of strange issues: sometimes browser may decide to ignore QUIC
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	184 Cache clearing/restart might help. Always check access.log and
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	185 error.log to make sure the browser is using HTTP/3 and not TCP https.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	186
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	187 * Console clients
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	188
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	189 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	190
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	191 $ examples/client 127.0.0.1 8443 https://example.com:8443/index.html
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	192
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	193 $ ./neqo-client https://127.0.0.1:8443/
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	194
8982 8f5d0ade0da7 README: updated to QUICv1. Sergey Kandaurov <pluknet@nginx.com> parents: 8966 diff changeset	195 $ chromium-build/out/my_build/quic_client http://example.com:8443
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	196
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	197
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	198 In case everyhing is right, the access log should show something like:
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	199
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	200 127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-"
8788 f0882db8c8d4 HTTP/3: removed $http3 that served its purpose. Sergey Kandaurov <pluknet@nginx.com> parents: 8787 diff changeset	201 "nghttp3/ngtcp2 client" "quic"
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	202
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	203
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	204 5. Troubleshooting
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	205
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	206 Here are some tips that may help to identify problems:
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	207
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	208 + Ensure nginx is built with proper SSL library that supports QUIC
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	209
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	210 + Ensure nginx is using the proper SSL library in runtime
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	211 (`nginx -V` shows what it's using)
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	212
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	213 + Ensure a client is actually sending requests over QUIC
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	214 (see "Clients" section about browsers and cache)
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	215
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	216 We recommend to start with simple console client like ngtcp2
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	217 to ensure the server is configured properly before trying
8395 578563babbd1 Fixed a typo. Vladimir Homutov <vl@nginx.com> parents: 8390 diff changeset	218 with real browsers that may be very picky with certificates,
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	219 for example.
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	220
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	221 + Build nginx with debug support [9] and check the debug log.
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	222 It should contain all details about connection and why it
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	223 failed. All related messages contain "quic " prefix and can
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	224 be easily filtered out.
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	225
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	226 + For a deeper investigation, please enable additional debugging
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	227 in src/event/quic/ngx_event_quic_connection.h:
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	228
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	229 #define NGX_QUIC_DEBUG_PACKETS
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	230 #define NGX_QUIC_DEBUG_FRAMES
8657 2dfc5ef29973 QUIC: introduced QUIC buffers. Roman Arutyunyan <arut@nginx.com> parents: 8601 diff changeset	231 #define NGX_QUIC_DEBUG_ALLOC
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	232 #define NGX_QUIC_DEBUG_CRYPTO
3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	233
8410 c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	234 6. Contributing
c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	235
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	236 Please refer to
8410 c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	237 http://nginx.org/en/docs/contributing_changes.html
c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	238
c7d1b500bd0a Updated README with "Contributing" section and draft details. Vladimir Homutov <vl@nginx.com> parents: 8402 diff changeset	239 7. Links
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	240
8787 8422570f6af4 README: updated after QUIC RFC publication, nginx 1.21 rebase. Sergey Kandaurov <pluknet@nginx.com> parents: 8763 diff changeset	241 [1] https://datatracker.ietf.org/doc/html/rfc9000
9019 0e74a77c2475 README: updated after HTTP/3 RFC publication, minor refinements. Sergey Kandaurov <pluknet@nginx.com> parents: 8984 diff changeset	242 [2] https://datatracker.ietf.org/doc/html/rfc9114
8984 a7b789e2be27 README: updated link to nginx-devel mailman. Sergey Kandaurov <pluknet@nginx.com> parents: 8983 diff changeset	243 [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
8366 3e894ace66ee Added README. Vladimir Homutov <vl@nginx.com> parents: diff changeset	244 [4] https://boringssl.googlesource.com/boringssl/
9034 79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	245 [5] https://www.libressl.org/
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	246 [6] https://github.com/quictls/openssl
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	247 [7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	248 [8] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	249 [9] https://nginx.org/en/docs/debugging_log.html
79cd6993a3e3 README: converted to passive voice, LibreSSL support. Sergey Kandaurov <pluknet@nginx.com> parents: 9028 diff changeset	250 [10] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf

Mercurial > hg > nginx

annotate README @ 9045:c6580dce98a8 quic