<!-- review: finished -->

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

# HTTP/3

Обеспечивает поддержку протокола
[HTTP/3](https://datatracker.ietf.org/doc/html/rfc9114)
для соединений с клиентами,
а также для соединений с проксируемыми серверами,
настраиваемых при помощи следующих директив из модуля
[Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy):

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

При [сборке из исходного кода](https://angie.software//angie/docs/installation/sourcebuild.md#sourcebuild) модуль не собирается по умолчанию; его необходимо
включить с помощью [параметра сборки](https://angie.software//angie/docs/installation/sourcebuild.md#configure)
`‑‑with‑http_v3_module`.
В пакетах и образах из
[наших репозиториев](https://angie.software//angie/docs/installation/index.md#install-packages)
модуль включен в сборку.

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

## Пример конфигурации

```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 {
        # для лучшей совместимости рекомендуется
        # использовать одинаковый порт для http/3 и https
        listen 8443 quic reuseport;
        listen 8443 ssl;

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

        location / {
            # используется для объявления о поддержке http/3
            add_header Alt-Svc 'h3=":8443"; ma=86400';
        }
    }
}
```

#### NOTE
Чтобы принимать HTTP/3-соединения по TLS, необходимо наличие поддержки
протокола TLSv1.3, появившейся в [OpenSSL](http://www.openssl.org/) версии
1.1.1.

Для поддержки 0-RTT нужна библиотека OpenSSL версии 3.5.1 или выше. Также
возможно использование библиотек [BoringSSL](https://boringssl.googlesource.com/boringssl/),
[LibreSSL](https://www.libressl.org) или
[QuicTLS](https://github.com/quictls/openssl).

До версии 1.29.1 поддержка 0-RTT не могла быть разрешена при использовании
OpenSSL независимо от значения директивы [ssl_early_data](https://angie.software//angie/docs/configuration/modules/http/http_ssl.md#ssl-early-data).

Для запросов HTTP/3, если заголовок `Host` не передан, переменная
`$http_host` инициализируется значением псевдозаголовка
`:authority`.

Кроме того, опцию `reuseport` можно указать только в одной из директив
`listen ... quic` на сервере.
Остальные директивы `listen ... quic` должны быть указаны без нее.

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

## Директивы

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

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

### http3

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3`  `on` | `off`;   |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию                                                                             | `http3 on;`              |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server             |

Разрешает согласование протокола HTTP/3.

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

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

### http3_hq

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_hq`  `on` | `off`;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| По умолчанию                                                                             | `http3_hq off;`             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                |

Разрешает согласование протокола HTTP/0.9, используемого в [функциональных тестах QUIC](https://github.com/marten-seemann/quic-interop-runner).

#### WARNING
Включайте этот режим только для запуска специализированных тестов,
которым в явной форме необходим данный режим.

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

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

### http3_max_concurrent_streams

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_concurrent_streams` число;   |
|------------------------------------------------------------------------------------------|-----------------------------------------|
| По умолчанию                                                                             | `http3_max_concurrent_streams 128;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                            |

Инициализирует настройки HTTP/3 и QUIC,
а также задает максимальное число параллельных HTTP/3-потоков в соединении.

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

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

### http3_max_table_capacity

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_max_table_capacity` число;   |
|------------------------------------------------------------------------------------------|-------------------------------------|
| Значение по умолчанию                                                                    | `http3_max_table_capacity 4096;`    |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                        |

Определяет емкость [динамической таблицы](https://www.ietf.org/archive/id/draft-ietf-quic-qpack-20.html#name-dynamic-table)
для серверных соединений.

#### NOTE
Похожая директива [proxy_http3_max_table_capacity](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http3-max-table-capacity)
задает это значение для прокси-соединений.
Чтобы избежать ошибок, использование динамической таблицы
отключается при включенном кэшировании в режиме проксирования.

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

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

### http3_stream_buffer_size

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `http3_stream_buffer_size` размер;   |
|------------------------------------------------------------------------------------------|--------------------------------------|
| По умолчанию                                                                             | `http3_stream_buffer_size 64k;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                         |

Задает [размер](https://angie.software//angie/docs/configuration/configfile.md#syntax) буфера,
используемого для чтения и записи QUIC-потоков.

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

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

### quic_active_connection_id_limit

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_active_connection_id_limit` число;   |
|------------------------------------------------------------------------------------------|--------------------------------------------|
| По умолчанию                                                                             | `quic_active_connection_id_limit 2;`       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                               |

Устанавливает значение транспортного параметра QUIC `active_connection_id_limit`. Это максимальное значение ID соединений, возможное для хранения на сервере.

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

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

### quic_bpf

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_bpf` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию                                                                             | `quic_bpf off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | main                       |

Разрешает маршрутизацию пакетов QUIC при помощи [eBPF](https://ebpf.io/). Если маршрутизация включена, то обеспечивается поддержка миграции QUIC-соединений.

#### NOTE
Директива поддерживается только на Linux 5.7+.

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

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

### quic_gso

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_gso` `on` | `off`;   |
|------------------------------------------------------------------------------------------|----------------------------|
| По умолчанию                                                                             | `quic_gso off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server               |

Разрешает отправку оптимизированного пакетного режима при помощи segmentation offloading.

#### NOTE
Оптимизированная отправка поддерживается только на Linux с поддержкой `UDP_SEGMENT`.

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

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

### quic_host_key

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_host_key` файл;   |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию                                                                             | —                       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server            |

Задает файл с секретным ключом, применяемым при шифровании stateless reset и address validation токенов. По умолчанию создается случайный ключ при каждой перезагрузке. Токены, созданные при помощи старых ключей, не принимаются.

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

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

### quic_retry

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `quic_retry` `on` | `off`;   |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию                                                                             | `quic_retry off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http, server                 |

Разрешает функциональность [QUIC Address Validation](https://datatracker.ietf.org/doc/html/rfc9000#name-address-validation), в том числе отправку нового токена в Retry-пакете или NEW_TOKEN frame и валидацию токена, полученного в Initial-пакете.

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

## Встроенные переменные

Модуль http_v3 поддерживает следующие встроенные переменные:

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

### `$http3`

согласованный идентификатор протокола:

| `h3`   | для HTTP/3-соединений               |
|--------|-------------------------------------|
| `hq`   | для hq-соединений                   |
| `""`   | пустая строка для остальных случаев |

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

### `$quic_connection`

порядковый номер QUIC-соединения