nginx-site: xml/en/docs/quic.xml comparison

comparison 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

comparison

equal deleted inserted replaced

-:c7bf5c9a1174
+:23eedf89fd5d
 <!DOCTYPE article SYSTEM "../../../dtd/article.dtd">
 <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
+protocols is available since 1.25.0.
-as a separate <literal>nginx-quic</literal>
+Also, since 1.25.0, the QUIC and HTTP/3 support is available in
-<link id="linux">prebult Linux package</link>
+Linux <link doc="../linux_packages.xml">binary packages</link>.
-or as part of our
-<commercial_version>commercial subscription</commercial_version>
-in a separate <literal>nginx-plus-http3</literal> package.
 </para>
 <para>
 <note>
 The QUIC and HTTP/3 support is experimental, caveat emptor applies.
 </para>
 </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 &amp;&amp; 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>
 The build is configured using the <command>configure</command> command.
 Please refer to <link doc="configure.xml"/> for details.
 </para>
 <para>
-When configuring nginx, it is possible to enable QUIC and HTTP/3
+When configuring nginx, it is possible to enable QUIC and HTTP/3 using the
-using the following configuration options:
+<link doc="configure.xml" id="http_v3_module"><literal>--with-http_v3_module</literal></link>
+configuration parameter.
-<list type="tag">
-<tag-name>
-<literal>--with-http_v3_module</literal><br/>
-</tag-name>
-<tag-desc>
-enables QUIC and HTTP/3.
-</tag-desc>
-</list>
 </para>
 <para>
 An SSL library that provides QUIC support is recommended to build nginx, such as
 <link url="https://boringssl.googlesource.com/boringssl">BoringSSL</link>,
 <para>
 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         \
+./configure
---with-cc-opt="-I../boringssl/include"     \
+--with-debug
---with-ld-opt="-L../boringssl/build/ssl    \
+--with-http_v3_module
--L../boringssl/build/crypto"
+--with-cc-opt="-I../boringssl/include"
+--with-ld-opt="-L../boringssl/build/ssl
+-L../boringssl/build/crypto"
 </programlisting>
 </para>
 <para>
 Alternatively, nginx can be configured with
 <link url="https://github.com/quictls/openssl">QuicTLS</link>:
 <programlisting>
-./auto/configure --with-debug --with-http_v3_module         \
+./configure
---with-cc-opt="-I../quictls/build/include" \
+--with-debug
---with-ld-opt="-L../quictls/build/lib"
+--with-http_v3_module
+--with-cc-opt="-I../quictls/build/include"
+--with-ld-opt="-L../quictls/build/lib"
 </programlisting>
 </para>
 <para>
 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          \
+./configure
---with-cc-opt="-I../libressl/build/include" \
+--with-debug
---with-ld-opt="-L../libressl/build/lib"
+--with-http_v3_module
+--with-cc-opt="-I../libressl/build/include"
+--with-ld-opt="-L../libressl/build/lib"
 </programlisting>
 </para>
 <para>
 After configuration,
 <link doc="http/ngx_http_core_module.xml" id="reuseport">reuseport</link>
 parameter to make it work properly with multiple workers.
 </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>
 quic_retry on;
 </programlisting>
 GSO (Generic Segmentation Offloading):
 <programlisting>
 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 &lt;size&gt;;
-</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 &lt;filename&gt;;
 </programlisting>
 </para>
 <para>
 QUIC requires TLSv1.3 protocol version which is enabled by default
 in the <link doc="http/ngx_http_ssl_module.xml" id="ssl_protocols"/> directive.
 ssl_certificate     certs/example.com.crt;
 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';
 }
 }
 }
 </example>
 </para>
 </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>
 Tips that may help to identify problems:
 <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>
 Ensure nginx is using the proper SSL library in runtime
 (the <literal>nginx -V</literal> shows what it is currently used).
 </listitem>
 <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.
 </listitem>
 All related messages contain the “<literal>quic</literal>” prefix
 and can be easily filtered out.
 </listitem>
 <listitem>
-For a deeper investigation, please enable additional debugging in
+For a deeper investigation, additional debugging can be enabled
-<literal>src/event/quic/ngx_event_quic_connection.h</literal>:
+using the following macros:
+<literal>NGX_QUIC_DEBUG_PACKETS</literal>,
-<para>
+<literal>NGX_QUIC_DEBUG_FRAMES</literal>,
-<example>
+<literal>NGX_QUIC_DEBUG_ALLOC</literal>,
-#define NGX_QUIC_DEBUG_PACKETS
+<literal>NGX_QUIC_DEBUG_CRYPTO</literal>.
-#define NGX_QUIC_DEBUG_FRAMES
-#define NGX_QUIC_DEBUG_ALLOC
+<para>
-#define NGX_QUIC_DEBUG_CRYPTO
+<programlisting>
-</example>
+./configure
+--with-http_v3_module
+--with-debug
+--with-cc-opt="-DNGX_QUIC_DEBUG_PACKETS -DNGX_QUIC_DEBUG_CRYPTO"
+</programlisting>
 </para>
 </listitem>
 </list>
 </para>
 </section>
-<section id="contributing" name="Contributing">
-<para>
-Please refer to <link doc="contributing_changes.xml"/>.
-</para>
-</section>
 </article>

Mercurial > hg > nginx-site

comparison xml/en/docs/quic.xml @ 2964:23eedf89fd5d