<!-- review: finished -->

<a id="http-v3"></a>

# HTTP/3

Provides [HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114)
protocol support for client connections,
as well as for connections with proxied servers
configured using the following
[Proxy](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy) module
directives:

- [proxy_http3_hq](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-hq)
- [proxy_http3_max_concurrent_streams](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-concurrent-streams)
- [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
- [proxy_http3_stream_buffer_size](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-stream-buffer-size)
- [proxy_http_version](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version)
- [proxy_pass](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass)
- [proxy_quic_active_connection_id_limit](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-active-connection-id-limit)
- [proxy_quic_gso](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-gso)
- [proxy_quic_host_key](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-quic-host-key)

When [building from the source code](https://en.angie.software//angie/docs/installation/sourcebuild.md#sourcebuild),
this module isn't built by default;
it should be enabled with the
`‑‑with‑http_v3_module`
[build option](https://en.angie.software//angie/docs/installation/sourcebuild.md#configure).

In packages and images from [our repositories](https://en.angie.software//angie/docs/installation/index.md#install-packages),
the module is included in the build.

<a id="configuration-example-50"></a>

## Configuration Example

```nginx
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 http/3 and https
        listen 8443 quic reuseport;
        listen 8443 ssl;

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

        location / {
            # used to advertise the availability of HTTP/3
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}
```

#### NOTE
Note that accepting HTTP/3 connections over TLS requires the TLSv1.3 protocol support, which is available since [OpenSSL](http://www.openssl.org/) version 1.1.1.

0-RTT support requires OpenSSL 3.5.1 or higher. Alternatively, [BoringSSL](https://boringssl.googlesource.com/boringssl/), [LibreSSL](https://www.libressl.org), or [QuicTLS](https://github.com/quictls/openssl) can be used to build and run this module.

Before version 1.29.1, 0-RTT support could not be enabled with OpenSSL regardless of the [ssl_early_data](https://en.angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data) directive value.

For HTTP/3 requests, if the `Host` header is not passed, the `$http_host` variable is initialized from the `:authority` pseudo-header.

Also, the `reuseport` option can only be specified in one of the `listen ... quic` directives on a server. All other `listen ... quic` directives must be specified without it.

<a id="directives-53"></a>

## Directives

<a id="index-0"></a>

<a id="http3"></a>

### http3

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3` `on` | `off`;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | `http3 on;`             |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server            |

Enables HTTP/3 protocol negotiation.

<a id="index-1"></a>

<a id="http3-hq"></a>

### http3_hq

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_hq` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `http3_hq off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables HTTP/0.9 protocol negotiation used in [QUIC interoperability tests](https://github.com/marten-seemann/quic-interop-runner).

#### WARNING
Enable this mode only to run specialized tests that explicitly require it.

<a id="index-2"></a>

<a id="http3-max-concurrent-streams"></a>

### http3_max_concurrent_streams

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_concurrent_streams` number;   |
|------------------------------------------------------------------------------------------|------------------------------------------|
| Default                                                                                  | `http3_max_concurrent_streams 128;`      |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                             |

Initializes HTTP/3 and QUIC settings
and sets the maximum number of concurrent HTTP/3 request streams in a connection.

<a id="index-3"></a>

<a id="http3-max-table-capacity"></a>

### http3_max_table_capacity

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_table_capacity` number;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| Default                                                                                  | `http3_max_table_capacity 4096;`     |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                         |

Sets the [dynamic table](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
capacity for server connections.

#### NOTE
A similar [proxy_http3_max_table_capacity](https://en.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity) directive
does this for proxy connections.
To avoid errors,
dynamic table usage is disabled when proxying with caching is enabled.

<a id="index-4"></a>

<a id="http3-stream-buffer-size"></a>

### http3_stream_buffer_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_stream_buffer_size` size;   |
|------------------------------------------------------------------------------------------|------------------------------------|
| Default                                                                                  | `http3_stream_buffer_size 64k;`    |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                       |

Sets the [size](https://en.angie.software//angie/docs/configuration/configfile.md#syntax) of the buffer used for reading and writing of the QUIC streams.

<a id="index-5"></a>

<a id="quic-active-connection-id-limit"></a>

### quic_active_connection_id_limit

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_active_connection_id_limit` number;   |
|------------------------------------------------------------------------------------------|---------------------------------------------|
| Default                                                                                  | `quic_active_connection_id_limit 2;`        |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                                |

Sets the QUIC active_connection_id_limit transport parameter value. This is the maximum number of connection IDs that can be stored on the server.

<a id="index-6"></a>

<a id="quic-bpf"></a>

### quic_bpf

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_bpf` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `quic_bpf off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | main                       |

Enables routing of QUIC packets using [eBPF](https://ebpf.io/). When enabled, this allows supporting QUIC connection migration.

#### NOTE
The directive is only supported on Linux 5.7+.

<a id="index-7"></a>

<a id="quic-gso"></a>

### quic_gso

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_gso` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| Default                                                                                  | `quic_gso off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server               |

Enables sending in optimized batch mode using segmentation offloading.

#### NOTE
Optimized sending is supported only on Linux featuring `UDP_SEGMENT`.

<a id="index-8"></a>

<a id="quic-host-key"></a>

### quic_host_key

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_host_key` file;   |
|------------------------------------------------------------------------------------------|-------------------------|
| Default                                                                                  | —                       |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server            |

Sets a file with the secret key used to encrypt stateless reset and address validation tokens. By default, a random key is generated on each reload. Tokens generated with old keys are not accepted.

<a id="index-9"></a>

<a id="quic-retry"></a>

### quic_retry

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_retry` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| Default                                                                                  | `quic_retry off;`            |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | http, server                 |

Enables the [QUIC Address Validation](https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation) feature. This includes sending a new token in a Retry packet or a NEW_TOKEN frame and validating a token received in the Initial packet.

<a id="built-in-variables-18"></a>

## Built-in Variables

The http_v3 module supports the following built-in variables:

<a id="v-http3"></a>

### `$http3`

negotiated protocol identifier:

| `h3`   | for HTTP/3 connections    |
|--------|---------------------------|
| `hq`   | for hq connections        |
| `""`   | an empty string otherwise |

<a id="v-quic-connection"></a>

### `$quic_connection`

QUIC connection serial number