nginx: README comparison

comparison README @ 9034:79cd6993a3e3 quic

README: converted to passive voice, LibreSSL support.

author	Sergey Kandaurov <pluknet@nginx.com>
date	Thu, 20 Oct 2022 16:30:43 +0400
parents	98e94553ae51
children	3c33d39a51d3

comparison

equal deleted inserted replaced

-:9076a74f1221
+:79cd6993a3e3
 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.
-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:
-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
 it should be possible to upload and download big files without errors.
 + The handshake completes successfully
 + Lost packets are detected and retransmitted properly
 + Clients may migrate to new address
 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
 $ 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 [5]
+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"
-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-stream_quic_module - enable QUIC in Stream
 3. Configuration
 HTTP/3 over QUIC on the specified port.
 The Stream "listen" directive got a new option "quic" which enables
 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:
 quic_retry on;
 To set host key for various tokens:
 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:
 http3_stream_buffer_size
 http3_max_concurrent_pushes
 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 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
 Known to work: ngtcp2, firefox's neqo and chromium's console clients:
 $ ./neqo-client https://127.0.0.1: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 "-"
 "nghttp3/ngtcp2 client" "quic"
 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)
 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,
 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
 failed. All related messages contain "quic " prefix and can
 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_FRAMES
 #define NGX_QUIC_DEBUG_ALLOC
 #define NGX_QUIC_DEBUG_CRYPTO
 6. Contributing
-If you are willing to contribute, please refer to
+Please refer to
 http://nginx.org/en/docs/contributing_changes.html
 7. Links
 [1] https://datatracker.ietf.org/doc/html/rfc9000
 [2] https://datatracker.ietf.org/doc/html/rfc9114
 [3] https://mailman.nginx.org/mailman3/lists/nginx-devel.nginx.org/
 [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

Mercurial > hg > nginx

comparison README @ 9034:79cd6993a3e3 quic