Mercurial > hg > nginx

changeset 9034:79cd6993a3e3 quic

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
README: converted to passive voice, LibreSSL support.
author Sergey Kandaurov <pluknet@nginx.com>
date Thu, 20 Oct 2022 16:30:43 +0400
parents 9076a74f1221
children 3be953161026
files README
diffstat 1 files changed, 50 insertions(+), 30 deletions(-) [+]
line wrap: on
line diff
--- a/README
+++ b/README
@@ -23,16 +23,17 @@ 1. Introduction
     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
-    the main NGINX codebase.  Thus, expect further updates of this code,
-    including features, changes in behaviour, bug fixes, and refactoring.
-    We'll be grateful for any feedback and code submissions.
+    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.
 
-    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.
@@ -52,24 +53,40 @@ 1. Introduction
 
 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
-    following new configuration options:
+    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"
+
+    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
@@ -82,8 +99,8 @@ 3. Configuration
     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"
-    option [6] to make it work properly with multiple workers.
+    Along with "http3" or "quic", it's also possible to specify "reuseport"
+    option [8] to make it work properly with multiple workers.
 
     To enable address validation:
 
@@ -110,8 +127,9 @@ 3. Configuration
         quic_host_key <filename>;
 
 
-    By default, GSO Linux-specific optimization [8] is disabled.
-    Enable if your network interface is configured to support GSO.
+    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:
 
@@ -164,7 +182,7 @@ 4. Clients
 
         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
 
@@ -177,7 +195,7 @@ 4. Clients
         $ 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"
@@ -185,28 +203,28 @@ 4. Clients
 
 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
-      (`nginx -V` will show you what you are using)
+    + Ensure nginx is using the proper SSL library in runtime
+      (`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
-      additional debugging in src/event/quic/ngx_event_quic_connection.h:
+    + 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
@@ -215,7 +233,7 @@ 5. Troubleshooting
 
 6. Contributing
 
-    If you are willing to contribute, please refer to
+    Please refer to
     http://nginx.org/en/docs/contributing_changes.html
 
 7. Links
@@ -224,7 +242,9 @@ 7. Links
     [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
-    [6] https://nginx.org/en/docs/http/ngx_http_core_module.html#listen
-    [7] https://nginx.org/en/docs/debugging_log.html
-    [8] http://vger.kernel.org/lpc_net2018_talks/willemdebruijn-lpc2018-udpgso-paper-DRAFT-1.pdf
+    [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