Support for QUIC and HTTP/3

对QUIC和HTTP/3的支持

Building from sources
从源代码构建
Configuration
配置
Example Configuration
配置示例
Troubleshooting
故障排查

Support for QUIC and HTTP/3 protocols is available since 1.25.0. Also, since 1.25.0, the QUIC and HTTP/3 support is available in Linux binary packages.

nginx从1.25.0起支持QUIC和HTTP/3协议。从1.25.0起，Linux的二进制软件包也支持 QUIC 和 HTTP/3。

The QUIC and HTTP/3 support is experimental, caveat emptor applies.

QUIC和HTTP/3的支持是试验性的，请谨慎使用。

Building from sources
从源代码构建

The build is configured using the configure command. Please refer to Building nginx from Sources for details.

使用configure命令配置构建。详情请参阅从源代码构建nginx

When configuring nginx, it is possible to enable QUIC and HTTP/3 using the --with-http_v3_module configuration parameter.

配置nginx时，可以使用--with-http_v3_module配置参数启用QUIC和HTTP/3。

An SSL library that provides QUIC support is recommended to build nginx, such as BoringSSL, LibreSSL, or QuicTLS. Otherwise, the OpenSSL compatibility layer will be used that does not support early data.

在构建nginx时建议使用支持QUIC的SSL库，如BoringSSL、LibreSSL或QuicTLS。否则，将使用不支持早期数据的OpenSSL兼容层。

Use the following command to configure nginx with BoringSSL:

使用如下命令配置BoringSSL 

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../boringssl/include"
    --with-ld-opt="-L../boringssl/build/ssl
                   -L../boringssl/build/crypto"

Alternatively, nginx can be configured with QuicTLS:

nginx也可以配置QuicTLS 

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../quictls/build/include"
    --with-ld-opt="-L../quictls/build/lib"

Alternatively, nginx can be configured with a modern version of LibreSSL:

nginx也可以配置LibreSSL 

./configure
    --with-debug
    --with-http_v3_module
    --with-cc-opt="-I../libressl/build/include"
    --with-ld-opt="-L../libressl/build/lib"

After configuration, nginx is compiled and installed using make.

配置完成后，nginx使用make命令编译、安装

Configuration

The listen directive in ngx_http_core_module module got a new parameter quic which enables HTTP/3 over QUIC on the specified port.

Along with the quic parameter it is also possible to specify the reuseport parameter to make it work properly with multiple workers.

For the list of directives, see ngx_http_v3_module.

To enable address validation: 

quic_retry on;

To enable 0-RTT: 

ssl_early_data on;

To enable GSO (Generic Segmentation Offloading): 

quic_gso on;

To set host key for various tokens: 

quic_host_key <filename>;

QUIC requires TLSv1.3 protocol version which is enabled by default in the ssl_protocols directive.

By default, GSO Linux-specific optimization is disabled. Enable it in case a corresponding network interface is configured to support GSO.

Example Configuration

http {
    log_format quic '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" "$http3"';

    access_log logs/access.log quic;

    server {
        # for better compatibility it's recommended
        # to use the same port for quic and https
        listen 8443 quic reuseport;
        listen 8443 ssl;

        ssl_certificate     certs/example.com.crt;
        ssl_certificate_key certs/example.com.key;

        location / {
            # required for browsers to direct them to quic port
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}

Troubleshooting

Tips that may help to identify problems: