2020-04-28 23:16:13 +08:00
|
|
|
Experimental QUIC support for nginx
|
|
|
|
-----------------------------------
|
|
|
|
|
|
|
|
1. Introduction
|
|
|
|
2. Installing
|
|
|
|
3. Configuration
|
|
|
|
4. Clients
|
|
|
|
5. Troubleshooting
|
2020-05-25 23:37:43 +08:00
|
|
|
6. Contributing
|
|
|
|
7. Links
|
2020-04-28 23:16:13 +08:00
|
|
|
|
|
|
|
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
|
2020-05-27 01:41:43 +08:00
|
|
|
on nginx mainline 1.19.x. We are planning to merge new nginx
|
2020-04-28 23:16:13 +08:00
|
|
|
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:
|
|
|
|
|
2020-06-23 16:57:00 +08:00
|
|
|
Currently we support IETF-QUIC draft-27, draft-28, draft-29.
|
|
|
|
Earlier drafts are NOT supported as they have incompatible wire format.
|
2020-04-28 23:16:13 +08:00
|
|
|
|
2020-05-25 23:37:43 +08:00
|
|
|
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.
|
|
|
|
|
2020-04-28 23:16:13 +08:00
|
|
|
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
|
2020-05-14 22:22:29 +08:00
|
|
|
+ 0-RTT data is being received and acted on
|
2020-04-28 23:16:13 +08:00
|
|
|
+ Connection is established using TLS Resume Ticket
|
2020-05-14 21:33:46 +08:00
|
|
|
+ A handshake that includes a Retry packet completes successfully
|
2020-04-28 23:16:13 +08:00
|
|
|
+ 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
|
2020-08-21 19:55:32 +08:00
|
|
|
+ Version Negotiation packet is sent to client with unknown version
|
|
|
|
+ Lost packets are detected and retransmitted properly
|
2020-04-28 23:16:13 +08:00
|
|
|
|
|
|
|
Not (yet) supported features:
|
|
|
|
|
2020-08-21 19:55:32 +08:00
|
|
|
- Explicit Congestion Notification (ECN) as specified in quic-recovery [5]
|
2020-04-28 23:16:13 +08:00
|
|
|
- A connection with the spin bit succeeds and the bit is spinning
|
|
|
|
- Structured Logging
|
|
|
|
- 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
|
|
|
|
|
2020-04-30 20:59:14 +08:00
|
|
|
$ hg clone -b quic https://hg.nginx.org/nginx-quic
|
2020-04-28 23:16:13 +08:00
|
|
|
$ cd nginx-quic
|
2020-04-30 20:47:43 +08:00
|
|
|
$ ./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"
|
2020-04-28 23:16:13 +08:00
|
|
|
$ make
|
|
|
|
|
2020-07-22 18:45:34 +08:00
|
|
|
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
|
|
|
|
|
2020-04-28 23:16:13 +08:00
|
|
|
3. Configuration
|
|
|
|
|
2020-07-22 18:45:34 +08:00
|
|
|
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.
|
2020-04-28 23:16:13 +08:00
|
|
|
|
2020-07-22 18:45:34 +08:00
|
|
|
Along with "http3" or "quic", you also have to specify "reuseport"
|
|
|
|
option [6] to make it work properly with multiple workers.
|
2020-04-28 23:16:13 +08:00
|
|
|
|
|
|
|
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
|
|
|
|
|
2020-05-23 19:41:08 +08:00
|
|
|
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;
|
|
|
|
|
2020-07-28 20:53:42 +08:00
|
|
|
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
|
|
|
|
|
2020-04-28 23:16:13 +08:00
|
|
|
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
|
2020-05-22 23:22:00 +08:00
|
|
|
add_header Alt-Svc '$http3=":8443"; ma=86400';
|
2020-04-28 23:16:13 +08:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
2020-09-11 15:56:05 +08:00
|
|
|
$ ./chrome --enable-quic --quic-version=h3-29 \
|
2020-04-28 23:16:13 +08:00
|
|
|
--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 \
|
2020-09-11 15:56:05 +08:00
|
|
|
--quic_version=h3-29 \
|
2020-04-28 23:16:13 +08:00
|
|
|
--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 "-"
|
2020-09-11 15:56:05 +08:00
|
|
|
"nghttp3/ngtcp2 client" "quic" "h3-29"
|
2020-04-28 23:16:13 +08:00
|
|
|
|
|
|
|
|
|
|
|
5. Troubleshooting
|
|
|
|
|
|
|
|
Here are some tips that may help you to identify problems:
|
|
|
|
|
|
|
|
+ Ensure you are building with proper SSL library that
|
2020-09-11 15:56:05 +08:00
|
|
|
implements draft 29
|
2020-04-28 23:16:13 +08:00
|
|
|
|
|
|
|
+ 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
|
2020-05-22 23:16:34 +08:00
|
|
|
with real browsers that may be very picky with certificates,
|
2020-04-28 23:16:13 +08:00
|
|
|
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
|
|
|
|
|
2020-05-25 23:37:43 +08:00
|
|
|
6. Contributing
|
|
|
|
|
|
|
|
If you are willing to contribute, please refer to
|
|
|
|
http://nginx.org/en/docs/contributing_changes.html
|
|
|
|
|
|
|
|
7. Links
|
2020-04-28 23:16:13 +08:00
|
|
|
|
2020-09-11 15:56:05 +08:00
|
|
|
[1] https://tools.ietf.org/html/draft-ietf-quic-transport-29
|
|
|
|
[2] https://tools.ietf.org/html/draft-ietf-quic-http-29
|
2020-04-28 23:16:13 +08:00
|
|
|
[3] https://mailman.nginx.org/mailman/listinfo/nginx-devel
|
|
|
|
[4] https://boringssl.googlesource.com/boringssl/
|
2020-09-11 15:56:05 +08:00
|
|
|
[5] https://tools.ietf.org/html/draft-ietf-quic-recovery-29
|
2020-04-28 23:16:13 +08:00
|
|
|
[6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
|
|
|
|
[7] https://nginx.org/en/docs/debugging_log.html
|