Модуль ngx_stream_core_module

• Пример конфигурации
• Директивы
• listen
• preread_buffer_size
• preread_timeout
• proxy_protocol_timeout
• resolver
• resolver_timeout
• server
• server_name
• server_names_hash_bucket_size
• server_names_hash_max_size
• stream
• tcp_nodelay
• variables_hash_bucket_size
• variables_hash_max_size
• Встроенные переменные

Модуль ngx_stream_core_module доступен начиная с версии 1.9.0. По умолчанию модуль не собирается; для его включения необходимо использовать параметр конфигурации --with-stream.

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

worker_processes auto;

error_log /var/log/nginx/error.log info;

events {
    worker_connections  1024;
}

stream {
    upstream backend {
        hash $remote_addr consistent;

        server backend1.example.com:12345 weight=5;
        server 127.0.0.1:12345            max_fails=3 fail_timeout=30s;
        server unix:/tmp/backend3;
    }

    upstream dns {
       server 192.168.0.1:53535;
       server dns.example.com:53;
    }

    server {
        listen 12345;
        proxy_connect_timeout 1s;
        proxy_timeout 3s;
        proxy_pass backend;
    }

    server {
        listen 127.0.0.1:53 udp reuseport;
        proxy_timeout 20s;
        proxy_pass dns;
    }

    server {
        listen [::1]:12345;
        proxy_pass unix:/tmp/stream.socket;
    }
}

Директивы

Задаёт address и port сокета, на котором сервер будет принимать соединения. Можно указать только порт. Адрес также может быть именем хоста, например:

listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # same as *:12345
listen localhost:12345;

Адреса IPv6 указываются в квадратных скобках:

listen [::1]:12345;
listen [::]:12345;

Сокеты домена UNIX указываются с префиксом «unix:»:

listen unix:/var/run/nginx.sock;

Диапазоны портов (1.15.10) указываются через дефис: сначала первый, затем последний порт:

listen 127.0.0.1:12345-12399;
listen 12345-12399;

Параметр default_server, если он указан, назначает сервер сервером по умолчанию для указанной пары address:port (1.25.5). Если ни в одной из директив не указан параметр default_server, сервер с первой парой address:port будет сервером по умолчанию для этой пары.

Параметр ssl позволяет указать, что все соединения, принимаемые на этом порту, должны работать в режиме SSL.

Параметр udp настраивает прослушивающий сокет для работы с дейтаграммами (1.9.13). Чтобы обрабатывать пакеты с одного и того же адреса и порта в одном сеансе, также следует указать параметр reuseport.

Параметр proxy_protocol (1.11.4) позволяет указать, что все соединения, принимаемые на этом порту, должны использовать протокол PROXY.

Версия 2 протокола PROXY поддерживается начиная с версии 1.13.11.

Директива listen может иметь несколько дополнительных параметров, относящихся к системным вызовам, связанным с сокетами. Эти параметры можно указывать в любой директиве listen, но только один раз для заданной пары address:port.

setfib=number

этот параметр (1.25.5) задаёт связанную таблицу маршрутизации, FIB (параметр SO_SETFIB) для прослушивающего сокета. В настоящее время работает только во FreeBSD.

fastopen=number

включает «TCP Fast Open» для прослушивающего сокета (1.21.0) и ограничивает максимальную длину очереди соединений, для которых ещё не завершено трёхэтапное рукопожатие.

Не включайте эту функцию, если сервер не может обрабатывать получение одного и того же SYN-пакета с данными более одного раза.

backlog=number

задаёт параметр backlog в вызове listen(), который ограничивает максимальную длину очереди ожидающих соединений (1.9.2). По умолчанию backlog устанавливается в -1 во FreeBSD, DragonFly BSD и macOS, а на других платформах — в 511.

rcvbuf=size

задаёт размер буфера приёма (параметр SO_RCVBUF) для прослушивающего сокета (1.11.13).

sndbuf=size

задаёт размер буфера отправки (параметр SO_SNDBUF) для прослушивающего сокета (1.11.13).

accept_filter=filter

задаёт имя фильтра приёма (параметр SO_ACCEPTFILTER) для прослушивающего сокета, который фильтрует входящие соединения до передачи их в accept() (1.25.5). Работает только во FreeBSD и NetBSD 5.0+. Возможные значения: dataready и httpready.

deferred

указывает использовать отложенный accept() (параметр сокета TCP_DEFER_ACCEPT) в Linux (1.25.5).

bind

этот параметр указывает выполнять отдельный вызов bind() для заданной пары адрес:порт. Дело в том, что если есть несколько директив listen с одним и тем же портом, но разными адресами, и одна из директив listen прослушивает все адреса для заданного порта (*:port), nginx будет bind() только для *:port. В этом случае для определения адреса, на котором было принято соединение, выполняется системный вызов getsockname(). Если используются параметры setfib, fastopen, backlog, rcvbuf, sndbuf, accept_filter, deferred, ipv6only, reuseport, multipath или so_keepalive, для заданной пары address:port всегда будет выполняться отдельный вызов bind().

ipv6only=on|off

этот параметр определяет (с помощью параметра сокета IPV6_V6ONLY), будет ли сокет IPv6, прослушивающий адрес-джокер [::], принимать только соединения IPv6 или соединения IPv6 и IPv4. По умолчанию этот параметр включён. Его можно задать только один раз при запуске.

reuseport

этот параметр (1.9.1) указывает создавать отдельный прослушивающий сокет для каждого рабочего процесса (с использованием параметра сокета SO_REUSEPORT в Linux 3.9+ и DragonFly BSD или SO_REUSEPORT_LB во FreeBSD 12+), позволяя ядру распределять входящие соединения между рабочими процессами. В настоящее время работает только в Linux 3.9+, DragonFly BSD и FreeBSD 12+ (1.15.1).

Неправильное использование этого параметра может иметь последствия для безопасности.

multipath

этот параметр (1.29.7) настраивает протокол Multipath TCP (IPPROTO_MPTCP) для прослушивающего сокета. В настоящее время работает только в Linux 5.6+.

Добавление или удаление этого параметра также включает параметр сокета SO_REUSEPORT, что может иметь последствия для безопасности.

so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]

этот параметр настраивает поведение «TCP keepalive» для прослушивающего сокета. Если параметр не указан, для сокета действуют настройки операционной системы. Если параметру присвоено значение «on», для сокета включается параметр SO_KEEPALIVE. Если параметру присвоено значение «off», для сокета отключается параметр SO_KEEPALIVE. Некоторые операционные системы поддерживают настройку параметров TCP keepalive для каждого сокета с помощью параметров сокета TCP_KEEPIDLE, TCP_KEEPINTVL и TCP_KEEPCNT. В таких системах (в настоящее время это Linux, NetBSD, Dragonfly, FreeBSD и macOS) их можно настроить с помощью параметров keepidle, keepintvl и keepcnt. Один или два параметра можно опустить; в этом случае для соответствующего параметра сокета будет использоваться системное значение по умолчанию. Например,

so_keepalive=30m::10

задаст время ожидания простоя (TCP_KEEPIDLE) равным 30 минутам, оставит интервал между проверками (TCP_KEEPINTVL) равным системному значению по умолчанию и задаст число проверок (TCP_KEEPCNT) равным 10.

До версии 1.25.5 разные серверы должны прослушивать разные пары address:port.

Задаёт size буфера предварительного чтения.

Задаёт timeout фазы предварительного чтения.

Задаёт timeout для завершения чтения заголовка протокола PROXY. Если за это время заголовок не будет передан целиком, соединение закрывается.

Настраивает серверы имён, используемые для преобразования имён вышестоящих серверов в адреса, например:

resolver 127.0.0.1 [::1]:5353;

Адрес можно указать в виде доменного имени или IP-адреса, при необходимости добавив порт. Если порт не указан, используется порт 53. Запросы к серверам имён выполняются по кругу.

По умолчанию nginx при разрешении имён ищет адреса IPv4 и IPv6. Если поиск адресов IPv4 или IPv6 не требуется, можно указать параметр ipv4=off (1.23.1) или ipv6=off.

По умолчанию nginx кэширует ответы, используя значение TTL из ответа. Необязательный параметр valid позволяет переопределить его:

resolver 127.0.0.1 [::1]:5353 valid=30s;

Чтобы предотвратить подмену DNS, рекомендуется настраивать DNS-серверы в надёжной локальной сети с надлежащей защитой.

Необязательный параметр status_zone (1.17.1) включает сбор статистики запросов и ответов DNS-сервера в указанной zone. Параметр доступен в рамках нашей коммерческой подписки.

До версии 1.11.3 эта директива была доступна в рамках нашей коммерческой подписки.

Задаёт время ожидания при разрешении имён, например:

resolver_timeout 5s;

До версии 1.11.3 эта директива была доступна в рамках нашей коммерческой подписки.

Задаёт конфигурацию виртуального сервера. Чёткого разделения между виртуальными серверами, основанными на IP-адресе (IP-based), и серверами, основанными на имени (name-based, с использованием расширения TLS Server Name Indication (SNI, RFC 6066)) (1.25.5), нет. Вместо этого директивы listen описывают все адреса и порты, на которых сервер должен принимать соединения, а директива server_name перечисляет все имена серверов.

Задаёт имена виртуального сервера, например:

server {
    server_name example.com www.example.com;
}

Первое имя становится основным именем сервера.

В именах серверов можно использовать звёздочку («*») вместо первой или последней части имени:

server {
    server_name example.com *.example.com www.example.*;
}

Такие имена называются именами с подстановочными знаками.

Первые два упомянутых выше варианта можно объединить в один:

server {
    server_name .example.com;
}

В именах серверов также можно использовать регулярные выражения, поставив перед именем тильду («~»):

server {
    server_name www.example.com ~^www\d+\.example\.com$;
}

Регулярные выражения могут содержать захватываемые группы, которые впоследствии можно использовать в других директивах:

server {
    server_name ~^(www\.)?(.+)$;

    proxy_pass www.$2:12345;
}

Именованные захватываемые группы в регулярных выражениях создают переменные, которые впоследствии можно использовать в других директивах:

server {
    server_name ~^(www\.)?(?<domain>.+)$;

    proxy_pass www.$domain:12345;
}

Если параметру директивы присвоено значение «$hostname», подставляется имя хоста машины.

Поиск выполняется в следующем порядке приоритета и прекращается при первом совпадении:

1. точное имя
2. самое длинное имя с подстановочным знаком в начале, например «*.example.com»
3. самое длинное имя с подстановочным знаком в конце, например «mail.*»
4. первое совпавшее регулярное выражение (в порядке появления в файле конфигурации)

Задаёт размер сегмента хеш-таблиц имён серверов. Значение по умолчанию зависит от размера строки кэша процессора. Подробности настройки хеш-таблиц приведены в отдельном документе.

Задаёт максимальный size хеш-таблиц имён серверов. Подробности настройки хеш-таблиц приведены в отдельном документе.

Определяет контекст файла конфигурации, в котором задаются директивы сервера stream.

Включает или отключает использование параметра TCP_NODELAY. Этот параметр включён как для соединений с клиентами, так и для соединений с проксируемыми серверами.

Задаёт размер сегмента хеш-таблицы переменных. Подробности настройки хеш-таблиц приведены в отдельном документе.

Задаёт максимальный size хеш-таблицы переменных. Подробности настройки хеш-таблиц приведены в отдельном документе.

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

Модуль ngx_stream_core_module поддерживает переменные начиная с версии 1.11.2.

$binary_remote_addr

адрес клиента в двоичном формате; длина значения всегда равна 4 байтам для адресов IPv4 или 16 байтам для адресов IPv6

$bytes_received

количество байтов, полученных от клиента (1.11.4)

$bytes_sent

количество байтов, отправленных клиенту

$connection

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

$hostname

имя хоста

$msec

текущее время в секундах с точностью до миллисекунд

$nginx_version

версия nginx

$pid

PID рабочего процесса

$protocol

протокол, используемый для обмена данными с клиентом: TCP или UDP (1.11.4)

$proxy_protocol_addr

адрес клиента из заголовка протокола PROXY (1.11.4)

Перед использованием протокол PROXY необходимо включить, указав параметр proxy_protocol в директиве listen.

$proxy_protocol_port

порт клиента из заголовка протокола PROXY (1.11.4)

Перед использованием протокол PROXY необходимо включить, указав параметр proxy_protocol в директиве listen.

$proxy_protocol_server_addr

адрес сервера из заголовка протокола PROXY (1.17.6)

Перед использованием протокол PROXY необходимо включить, указав параметр proxy_protocol в директиве listen.

$proxy_protocol_server_port

порт сервера из заголовка протокола PROXY (1.17.6)

Перед использованием протокол PROXY необходимо включить, указав параметр proxy_protocol в директиве listen.

$proxy_protocol_tlv_name

TLV из заголовка протокола PROXY (1.23.2). name может быть именем типа TLV или его числовым значением. В последнем случае значение указывается в шестнадцатеричном формате с префиксом 0x:

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

SSL TLV также можно получить по имени типа TLV или его числовому значению; в обоих случаях перед ним указывается префикс ssl_:

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

Поддерживаются следующие имена типов TLV:

• alpn (0x01) — протокол верхнего уровня, используемый в соединении
• authority (0x02) — значение имени хоста, переданное клиентом
• unique_id (0x05) — уникальный идентификатор соединения
• netns (0x30) — имя пространства имён
• ssl (0x20) — двоичная структура SSL TLV

Поддерживаются следующие имена типов SSL TLV:

• ssl_version (0x21) — версия SSL, используемая в соединении с клиентом
• ssl_cn (0x22) — общее имя сертификата SSL
• ssl_cipher (0x23) — имя используемого шифра
• ssl_sig_alg (0x24) — алгоритм, использованный для подписи сертификата
• ssl_key_alg (0x25) — алгоритм открытого ключа

Также поддерживается следующее специальное имя типа SSL TLV:

• ssl_verify — результат проверки сертификата SSL клиента: ноль, если клиент предоставил сертификат и он успешно прошёл проверку, и ненулевое значение в противном случае

Перед использованием протокол PROXY необходимо включить, указав параметр proxy_protocol в директиве listen.

$remote_addr

адрес клиента

$remote_port

порт клиента

$server_addr

адрес сервера, принявшего соединение

Вычисление значения этой переменной обычно требует одного системного вызова. Чтобы избежать системного вызова, в директивах listen необходимо указать адреса и использовать параметр bind.

$server_port

порт сервера, принявшего соединение

$session_time

длительность сеанса в секундах с точностью до миллисекунд (1.11.4);

$status

состояние сеанса (1.11.4); может принимать одно из следующих значений:

200

сеанс успешно завершён

400

данные клиента не удалось разобрать, например заголовок протокола PROXY

403

доступ запрещён, например, когда доступ ограничен для определённых адресов клиентов

500

внутренняя ошибка сервера

502

ошибка шлюза, например если не удалось выбрать вышестоящий сервер или установить с ним соединение

503

служба недоступна, например, когда доступ ограничен количеством соединений

$time_iso8601

местное время в стандартном формате ISO 8601

$time_iso8601_ms

местное время в стандартном формате ISO 8601 с точностью до миллисекунд (1.29.8)

Эта переменная доступна в рамках нашей коммерческой подписки.

$time_local

местное время в формате Common Log Format