README: converted to passive voice, LibreSSL support.
This commit is contained in:
parent
34500dcac3
commit
3cd06a3a9a
80
README
80
README
@ -23,16 +23,17 @@ Experimental QUIC support for nginx
|
|||||||
The code is currently at a beta level of quality, however
|
The code is currently at a beta level of quality, however
|
||||||
there are several production deployments with it.
|
there are several production deployments with it.
|
||||||
|
|
||||||
We are working on improving HTTP/3 support to integrate it into
|
NGINX Development Team is working on improving HTTP/3 support to
|
||||||
the main NGINX codebase. Thus, expect further updates of this code,
|
integrate it into the main NGINX codebase. Thus, expect further
|
||||||
including features, changes in behaviour, bug fixes, and refactoring.
|
updates of this code, including features, changes in behaviour,
|
||||||
We'll be grateful for any feedback and code submissions.
|
bug fixes, and refactoring. NGINX Development team will be
|
||||||
|
grateful for any feedback and code submissions.
|
||||||
|
|
||||||
You can always contact us via nginx-devel mailing list [3].
|
Please contact NGINX Development Team via nginx-devel mailing list [3].
|
||||||
|
|
||||||
What works now:
|
What works now:
|
||||||
|
|
||||||
We support IETF QUIC version 1. Internet drafts are no longer supported.
|
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
|
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.
|
it should be possible to upload and download big files without errors.
|
||||||
@ -52,24 +53,40 @@ Experimental QUIC support for nginx
|
|||||||
|
|
||||||
2. Installing
|
2. Installing
|
||||||
|
|
||||||
You will need a BoringSSL [4] library that provides QUIC support
|
A library that provides QUIC support is required to build nginx, there
|
||||||
|
are several of those available on the market:
|
||||||
|
+ BoringSSL [4]
|
||||||
|
+ LibreSSL [5]
|
||||||
|
+ QuicTLS [6]
|
||||||
|
|
||||||
|
Clone the NGINX QUIC repository
|
||||||
|
|
||||||
$ hg clone -b quic https://hg.nginx.org/nginx-quic
|
$ hg clone -b quic https://hg.nginx.org/nginx-quic
|
||||||
$ cd nginx-quic
|
$ cd nginx-quic
|
||||||
|
|
||||||
|
Use the following command to configure nginx with BoringSSL [4]
|
||||||
|
|
||||||
$ ./auto/configure --with-debug --with-http_v3_module \
|
$ ./auto/configure --with-debug --with-http_v3_module \
|
||||||
--with-cc-opt="-I../boringssl/include" \
|
--with-cc-opt="-I../boringssl/include" \
|
||||||
--with-ld-opt="-L../boringssl/build/ssl \
|
--with-ld-opt="-L../boringssl/build/ssl \
|
||||||
-L../boringssl/build/crypto"
|
-L../boringssl/build/crypto"
|
||||||
$ make
|
$ make
|
||||||
|
|
||||||
Alternatively, nginx can be configured with QuicTLS [5]
|
Alternatively, nginx can be configured with QuicTLS [6]
|
||||||
|
|
||||||
$ ./auto/configure --with-debug --with-http_v3_module \
|
$ ./auto/configure --with-debug --with-http_v3_module \
|
||||||
--with-cc-opt="-I../quictls/build/include" \
|
--with-cc-opt="-I../quictls/build/include" \
|
||||||
--with-ld-opt="-L../quictls/build/lib"
|
--with-ld-opt="-L../quictls/build/lib"
|
||||||
|
|
||||||
When configuring nginx, you can enable QUIC and HTTP/3 using the
|
Alternatively, nginx can be configured with a modern version
|
||||||
following new configuration options:
|
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"
|
||||||
|
|
||||||
|
When configuring nginx, it's possible to enable QUIC and HTTP/3
|
||||||
|
using the following new configuration options:
|
||||||
|
|
||||||
--with-http_v3_module - enable QUIC and HTTP/3
|
--with-http_v3_module - enable QUIC and HTTP/3
|
||||||
--with-stream_quic_module - enable QUIC in Stream
|
--with-stream_quic_module - enable QUIC in Stream
|
||||||
@ -82,8 +99,8 @@ Experimental QUIC support for nginx
|
|||||||
The Stream "listen" directive got a new option "quic" which enables
|
The Stream "listen" directive got a new option "quic" which enables
|
||||||
QUIC as client transport protocol instead of TCP or plain UDP.
|
QUIC as client transport protocol instead of TCP or plain UDP.
|
||||||
|
|
||||||
Along with "http3" or "quic", you also have to specify "reuseport"
|
Along with "http3" or "quic", it's also possible to specify "reuseport"
|
||||||
option [6] to make it work properly with multiple workers.
|
option [8] to make it work properly with multiple workers.
|
||||||
|
|
||||||
To enable address validation:
|
To enable address validation:
|
||||||
|
|
||||||
@ -110,8 +127,9 @@ Experimental QUIC support for nginx
|
|||||||
quic_host_key <filename>;
|
quic_host_key <filename>;
|
||||||
|
|
||||||
|
|
||||||
By default, GSO Linux-specific optimization [8] is disabled.
|
By default, GSO Linux-specific optimization [10] is disabled.
|
||||||
Enable if your network interface is configured to support GSO.
|
Enable it in case a corresponding network interface is configured to
|
||||||
|
support GSO.
|
||||||
|
|
||||||
A number of directives were added that configure HTTP/3:
|
A number of directives were added that configure HTTP/3:
|
||||||
|
|
||||||
@ -164,7 +182,7 @@ Example configuration:
|
|||||||
|
|
||||||
Beware of strange issues: sometimes browser may decide to ignore QUIC
|
Beware of strange issues: sometimes browser may decide to ignore QUIC
|
||||||
Cache clearing/restart might help. Always check access.log and
|
Cache clearing/restart might help. Always check access.log and
|
||||||
error.log to make sure you are using HTTP/3 and not TCP https.
|
error.log to make sure the browser is using HTTP/3 and not TCP https.
|
||||||
|
|
||||||
* Console clients
|
* Console clients
|
||||||
|
|
||||||
@ -177,7 +195,7 @@ Example configuration:
|
|||||||
$ chromium-build/out/my_build/quic_client http://example.com:8443
|
$ chromium-build/out/my_build/quic_client http://example.com:8443
|
||||||
|
|
||||||
|
|
||||||
If you've got it right, in the access log you should see something like:
|
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 "-"
|
127.0.0.1 - - [24/Apr/2020:11:27:29 +0300] "GET / HTTP/3" 200 805 "-"
|
||||||
"nghttp3/ngtcp2 client" "quic"
|
"nghttp3/ngtcp2 client" "quic"
|
||||||
@ -185,28 +203,28 @@ Example configuration:
|
|||||||
|
|
||||||
5. Troubleshooting
|
5. Troubleshooting
|
||||||
|
|
||||||
Here are some tips that may help you to identify problems:
|
Here are some tips that may help to identify problems:
|
||||||
|
|
||||||
+ Ensure you are building with proper SSL library that supports QUIC
|
+ Ensure nginx is built with proper SSL library that supports QUIC
|
||||||
|
|
||||||
+ Ensure you are using the proper SSL library in runtime
|
+ Ensure nginx is using the proper SSL library in runtime
|
||||||
(`nginx -V` will show you what you are using)
|
(`nginx -V` shows what it's using)
|
||||||
|
|
||||||
+ Ensure your client is actually sending requests over QUIC
|
+ Ensure a client is actually sending requests over QUIC
|
||||||
(see "Clients" section about browsers and cache)
|
(see "Clients" section about browsers and cache)
|
||||||
|
|
||||||
We recommend to start with simple console client like ngtcp2
|
We recommend to start with simple console client like ngtcp2
|
||||||
to ensure you've got server configured properly before trying
|
to ensure the server is configured properly before trying
|
||||||
with real browsers that may be very picky with certificates,
|
with real browsers that may be very picky with certificates,
|
||||||
for example.
|
for example.
|
||||||
|
|
||||||
+ Build nginx with debug support [7] and check your debug log.
|
+ Build nginx with debug support [9] and check the debug log.
|
||||||
It should contain all details about connection and why it
|
It should contain all details about connection and why it
|
||||||
failed. All related messages contain "quic " prefix and can
|
failed. All related messages contain "quic " prefix and can
|
||||||
be easily filtered out.
|
be easily filtered out.
|
||||||
|
|
||||||
+ If you want to investigate deeper, you may want to enable
|
+ For a deeper investigation, please enable additional debugging
|
||||||
additional debugging in src/event/quic/ngx_event_quic_connection.h:
|
in src/event/quic/ngx_event_quic_connection.h:
|
||||||
|
|
||||||
#define NGX_QUIC_DEBUG_PACKETS
|
#define NGX_QUIC_DEBUG_PACKETS
|
||||||
#define NGX_QUIC_DEBUG_FRAMES
|
#define NGX_QUIC_DEBUG_FRAMES
|
||||||
@ -215,7 +233,7 @@ Example configuration:
|
|||||||
|
|
||||||
6. Contributing
|
6. Contributing
|
||||||
|
|
||||||
If you are willing to contribute, please refer to
|
Please refer to
|
||||||
http://nginx.org/en/docs/contributing_changes.html
|
http://nginx.org/en/docs/contributing_changes.html
|
||||||
|
|
||||||
7. Links
|
7. Links
|
||||||
@ -224,7 +242,9 @@ Example configuration:
|
|||||||
[2] https://datatracker.ietf.org/doc/html/rfc9114
|
[2] https://datatracker.ietf.org/doc/html/rfc9114
|
||||||
[3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
|
[3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
|
||||||
[4] https://boringssl.googlesource.com/boringssl/
|
[4] https://boringssl.googlesource.com/boringssl/
|
||||||
[5] https://github.com/quictls/openssl
|
[5] https://www.libressl.org/
|
||||||
[6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
|
[6] https://github.com/quictls/openssl
|
||||||
[7] https://nginx.org/en/docs/debugging_log.html
|
[7] https://github.com/libressl-portable/portable/releases/tag/v3.6.0
|
||||||
[8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf
|
[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
|
||||||
|
Loading…
x
Reference in New Issue
Block a user