Mercurial > hg > nginx-site
diff xml/en/docs/quic.xml @ 2964:23eedf89fd5d
Updated QUIC documentation after QUIC code merge.
- removed http3_max_concurrent_pushes, http3_push
http3_push_preload, quic_mtu
- updated apperared-in version
- update of quic.xml, adding Rus translation
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Tue, 23 May 2023 16:44:47 +0100 |
parents | cebca5ba84d7 |
children |
line wrap: on
line diff
--- a/xml/en/docs/quic.xml Wed May 10 18:59:39 2023 -0700 +++ b/xml/en/docs/quic.xml Tue May 23 16:44:47 2023 +0100 @@ -7,20 +7,18 @@ <article name="Support for QUIC and HTTP/3" link="/en/docs/quic.html" lang="en" - rev="1"> + rev="2"> <section> <para> +Support for <link url="https://datatracker.ietf.org/doc/html/rfc9000">QUIC</link> and <link url="https://datatracker.ietf.org/doc/html/rfc9114">HTTP/3</link> -protocols are supported since 1.23.4 and are available -as a separate <literal>nginx-quic</literal> -<link id="linux">prebult Linux package</link> -or as part of our -<commercial_version>commercial subscription</commercial_version> -in a separate <literal>nginx-plus-http3</literal> package. +protocols is available since 1.25.0. +Also, since 1.25.0, the QUIC and HTTP/3 support is available in +Linux <link doc="../linux_packages.xml">binary packages</link>. </para> <para> @@ -32,144 +30,6 @@ </section> -<section id="linux" name="Installation on Linux"> - -<para> -For Linux, <literal>nginx-quic</literal> packages -from nginx.org can be used. -The packages -are available for the following Linux distributions and -versions: -<list type="bullet"> - -<listitem> -<link id="rhel">RHEL 9 and derivatives</link>: amd64, arm64 -</listitem> - -<listitem> -<link id="rhel">Ubuntu 22.04</link>: amd64, arm64 -</listitem> - -</list> -</para> - -<para> -The <literal>nginx-quic</literal> packages are dynamically linked with the -<link url="https://github.com/quictls/openssl">QuicTLS</link> library. -It will be installed as a runtime dependency -alongside system-wide OpenSSL packages. -QuicTLS differs from operating system-provided OpenSSL package in the following: -<list type="bullet"> - -<listitem> -does not follow system-wide crypto policies -</listitem> - -<listitem> -does not have distribution-specific patches applied -</listitem> - -<listitem> -uses configuration from <literal>/etc/pki/quictls</literal> (RHEL9) -or <literal>/etc/quictls</literal> (Ubuntu 22.04) -</listitem> - -</list> -</para> - -<para> -The <literal>nginx-quic</literal> packages -cannot be installed alongside nginx or nginx-plus packages. -</para> - -<para> -Please back up your configuration files -before installing <literal>nginx-quic</literal>: -<programlisting> -sudo cp -a /etc/nginx /etc/nginx-quic-backup -</programlisting> -</para> - - -<section name="RHEL" id="rhel"> - -<para> -The <literal>nginx-quic</literal> package can be installed on -Red Hat Enterprise Linux and its derivatives such as -CentOS, Oracle Linux, Rocky Linux, AlmaLinux. -</para> - -<para> -Install the prerequisites: -<programlisting> -sudo dnf install yum-utils -</programlisting> - -To set up the yum repository, create the file named -<path>/etc/yum.repos.d/nginx-quic.repo </path> -with the following contents: - -<programlisting> -[nginx-quic] -name=nginx-quic repo -baseurl=https://packages.nginx.org/nginx-quic/rhel/9/$basearch/ -gpgcheck=1 -enabled=1 -gpgkey=https://nginx.org/keys/nginx_signing.key -</programlisting> - -To install nginx-quic, run the following commands: -<programlisting> -sudo dnf install nginx-quic -</programlisting> - -When prompted to accept the GPG key, verify that the fingerprint matches -<command>573B FD6B 3D8F BC64 1079 A6AB ABF5 BD82 7BD9 BF62</command>, -and if so, accept it. -</para> - -</section> - - -<section name="Ubuntu" id="ubuntu"> - -<para> -Install the prerequisites: -<programlisting> -sudo apt update && sudo apt install curl gnupg2 ca-certificates lsb-release ubuntu-keyring -</programlisting> -</para> - -<para> -Import an official nginx signing key so apt could verify the packages -authenticity. -Fetch the key: -<programlisting> -curl https://nginx.org/keys/nginx_signing.key | gpg --dearmor \ - | sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null -</programlisting> - -To set up the apt repository for nginx-quic packages, run the following command: -<programlisting> -echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg] \ - https://packages.nginx.org/nginx-quic/ubuntu `lsb_release -cs` nginx-quic" \ - | sudo tee /etc/apt/sources.list.d/nginx-quic.list -</programlisting> -</para> - -<para> -To install nginx-quic, run the following commands: -<programlisting> -sudo apt update -sudo apt install nginx-quic -</programlisting> -</para> - -</section> - -</section> - - <section id="building" name="Building from sources"> <para> @@ -178,19 +38,9 @@ </para> <para> -When configuring nginx, it is possible to enable QUIC and HTTP/3 -using the following configuration options: - -<list type="tag"> - -<tag-name> -<literal>--with-http_v3_module</literal><br/> -</tag-name> -<tag-desc> -enables QUIC and HTTP/3. -</tag-desc> - -</list> +When configuring nginx, it is possible to enable QUIC and HTTP/3 using the +<link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link> +configuration parameter. </para> <para> @@ -207,10 +57,12 @@ Use the following command to configure nginx with <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>: <programlisting> -./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" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../boringssl/include" + --with-ld-opt="-L../boringssl/build/ssl + -L../boringssl/build/crypto" </programlisting> </para> @@ -218,9 +70,11 @@ Alternatively, nginx can be configured with <link url="https://github.com/quictls/openssl">QuicTLS</link>: <programlisting> -./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../quictls/build/include" \ - --with-ld-opt="-L../quictls/build/lib" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../quictls/build/include" + --with-ld-opt="-L../quictls/build/lib" </programlisting> </para> @@ -228,9 +82,11 @@ Alternatively, nginx can be configured with a modern version of <link url="https://www.libressl.org">LibreSSL</link>: <programlisting> -./auto/configure --with-debug --with-http_v3_module \ - --with-cc-opt="-I../libressl/build/include" \ - --with-ld-opt="-L../libressl/build/lib" +./configure + --with-debug + --with-http_v3_module + --with-cc-opt="-I../libressl/build/include" + --with-ld-opt="-L../libressl/build/lib" </programlisting> </para> @@ -260,6 +116,11 @@ </para> <para> +For the list of directives, see +<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link>. +</para> + +<para> To <link doc="http/ngx_http_v3_module.xml" id="quic_retry">enable</link> address validation: <programlisting> @@ -278,18 +139,11 @@ quic_gso on; </programlisting> -To <link doc="http/ngx_http_v3_module.xml" id="quic_mtu">limit</link> -maximum UDP payload size on receive path: -<programlisting> -quic_mtu <size>; -</programlisting> - To <link doc="http/ngx_http_v3_module.xml" id="quic_host_key">set</link> host key for various tokens: <programlisting> quic_host_key <filename>; </programlisting> - </para> <para> @@ -329,7 +183,7 @@ ssl_certificate_key certs/example.com.key; location / { - # required for browsers to direct them into quic port + # required for browsers to direct them to quic port add_header Alt-Svc 'h3=":8443"; ma=86400'; } } @@ -340,17 +194,6 @@ </section> -<section id="directives" name="Directives"> - -<para> -For the list of directives, please refer to -<link doc="http/ngx_http_v3_module.xml">ngx_http_v3_module</link> -module documentation. -</para> - -</section> - - <section id="troubleshooting " name="Troubleshooting"> <para> @@ -358,7 +201,7 @@ <list type="bullet"> <listitem> -Ensure nginx is built with the proper SSL library that supports QUIC. +Ensure nginx is built with the proper SSL library. </listitem> <listitem> @@ -368,7 +211,7 @@ <listitem> Ensure a client is actually sending requests over QUIC. -We recommend starting with a simple console client such as +It is recommended to start with a simple console client such as <link url="https://nghttp2.org/ngtcp2">ngtcp2</link> to ensure the server is configured properly before trying with real browsers that may be quite picky with certificates. @@ -383,16 +226,20 @@ </listitem> <listitem> -For a deeper investigation, please enable additional debugging in -<literal>src/event/quic/ngx_event_quic_connection.h</literal>: +For a deeper investigation, additional debugging can be enabled +using the following macros: +<literal>NGX_QUIC_DEBUG_PACKETS</literal>, +<literal>NGX_QUIC_DEBUG_FRAMES</literal>, +<literal>NGX_QUIC_DEBUG_ALLOC</literal>, +<literal>NGX_QUIC_DEBUG_CRYPTO</literal>. <para> -<example> -#define NGX_QUIC_DEBUG_PACKETS -#define NGX_QUIC_DEBUG_FRAMES -#define NGX_QUIC_DEBUG_ALLOC -#define NGX_QUIC_DEBUG_CRYPTO -</example> +<programlisting> +./configure + --with-http_v3_module + --with-debug + --with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO" +</programlisting> </para> </listitem> @@ -401,13 +248,4 @@ </section> - -<section id="contributing" name="Contributing"> - -<para> -Please refer to <link doc="contributing_changes.xml"/>. -</para> - -</section> - </article>