Модуль 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;
    }
}

Директивы

Синтаксис: listen адрес:порт [default_server] [ssl] [udp] [proxy_protocol] [setfib=число] [fastopen=число] [backlog=число] [rcvbuf=размер] [sndbuf=размер] [accept_filter=фильтр] [deferred] [bind] [ipv6only=on|off] [reuseport] [so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]];
Умолчание:
Контекст: server

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

listen 127.0.0.1:12345;
listen *:12345;
listen 12345;     # то же, что и *: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, то сервер, в котором описана эта директива, будет сервером по умолчанию для указанной пары адрес:порт (1.25.5). Если же директив с параметром default_server нет, то сервером по умолчанию будет первый сервер, в котором описана пара адрес:порт.

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

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

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

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

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

setfib=число
этот параметр (1.25.5) задаёт таблицу маршрутизации, FIB (параметр SO_SETFIB) для слушающего сокета. В настоящий момент это работает только на FreeBSD.
fastopen=число
включает “TCP Fast Open” для слушающего сокета (1.21.0) и ограничивает максимальную длину очереди соединений, которые ещё не завершили процесс three-way handshake.
Не включайте “TCP Fast Open”, не убедившись, что сервер может адекватно обрабатывать многократное получение одного и того же SYN-пакета с данными.
backlog=число
задаёт параметр backlog в вызове listen(), который ограничивает максимальный размер очереди ожидающих приёма соединений (1.9.2). По умолчанию backlog устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ.
rcvbuf=размер
задаёт размер буфера приёма (параметр SO_RCVBUF) для слушающего сокета (1.11.13).
sndbuf=размер
задаёт размер буфера передачи (параметр SO_SNDBUF) для слушающего сокета (1.11.13).
accept_filter=фильтр
задаёт название accept-фильтра (параметр 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 слушает на всех адресах для данного порта (*:порт), то nginx сделает bind() только на *:порт. Необходимо заметить, что в этом случае для определения адреса, на которой пришло соединение, делается системный вызов getsockname(). Если же используются параметры setfib, fastopen, backlog, rcvbuf, sndbuf, accept_filter, deferred, ipv6only, reuseport или so_keepalive, то для данной пары адрес:порт всегда делается отдельный вызов bind().
ipv6only=on|off
этот параметр определяет (через параметр сокета IPV6_V6ONLY), будет ли слушающий на wildcard-адресе [::] 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).
Ненадлежащее использование параметра может быть небезопасно.
so_keepalive=on|off|[keepidle]:[keepintvl]:[keepcnt]
этот параметр конфигурирует для слушающего сокета поведение “TCP keepalive”. Если этот параметр опущен, то для сокета будут действовать настройки операционной системы. Если он установлен в значение “on”, то для сокета включается параметр SO_KEEPALIVE. Если он установлен в значение “off”, то для сокета параметр SO_KEEPALIVE выключается. Некоторые операционные системы поддерживают настройку параметров “TCP keepalive” на уровне сокета посредством параметров TCP_KEEPIDLE, TCP_KEEPINTVL и TCP_KEEPCNT. На таких системах (в настоящий момент это Linux 2.4+, NetBSD 5+ и FreeBSD 9.0-STABLE) их можно сконфигурировать с помощью параметров keepidle, keepintvl и keepcnt. Один или два параметра могут быть опущены, в таком случае для соответствующего параметра сокета будут действовать стандартные системные настройки. Например,
so_keepalive=30m::10
установит таймаут бездействия (TCP_KEEPIDLE) в 30 минут, для интервала проб (TCP_KEEPINTVL) будет действовать стандартная системная настройка, а счётчик проб (TCP_KEEPCNT) будет равен 10.

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

Синтаксис: preread_buffer_size размер;
Умолчание:
preread_buffer_size 16k;
Контекст: stream, server

Эта директива появилась в версии 1.11.5.

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

Синтаксис: preread_timeout время;
Умолчание:
preread_timeout 30s;
Контекст: stream, server

Эта директива появилась в версии 1.11.5.

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

Синтаксис: proxy_protocol_timeout время;
Умолчание:
proxy_protocol_timeout 30s;
Контекст: stream, server

Эта директива появилась в версии 1.11.4.

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

Синтаксис: resolver адрес ... [valid=время] [ipv4=on|off] [ipv6=on|off] [status_zone=зона];
Умолчание:
Контекст: stream, server

Эта директива появилась в версии 1.11.3.

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

resolver 127.0.0.1 [::1]:5353;

Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта. Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически.

По умолчанию 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 в указанной зоне. Параметр доступен как часть коммерческой подписки.

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

Синтаксис: resolver_timeout время;
Умолчание:
resolver_timeout 30s;
Контекст: stream, server

Эта директива появилась в версии 1.11.3.

Задаёт таймаут для преобразования имени в адрес, например:

resolver_timeout 5s;

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

Синтаксис: server { ... }
Умолчание:
Контекст: stream

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

Синтаксис: server_name имя ...;
Умолчание:
server_name "";
Контекст: server

Эта директива появилась в версии 1.25.5.

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

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”, то подставляется имя хоста (hostname) машины.

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

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

Синтаксис: server_names_hash_bucket_size размер;
Умолчание:
server_names_hash_bucket_size 32|64|128;
Контекст: stream

Эта директива появилась в версии 1.25.5.

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

Синтаксис: server_names_hash_max_size размер;
Умолчание:
server_names_hash_max_size 512;
Контекст: stream

Эта директива появилась в версии 1.25.5.

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

Синтаксис: stream { ... }
Умолчание:
Контекст: main

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

Синтаксис: tcp_nodelay on | off;
Умолчание:
tcp_nodelay on;
Контекст: stream, server

Эта директива появилась в версии 1.9.4.

Разрешает или запрещает использование параметра TCP_NODELAY. Параметр включается как для клиентских соединений, так и для соединений с проксируемыми серверами.

Синтаксис: variables_hash_bucket_size размер;
Умолчание:
variables_hash_bucket_size 64;
Контекст: stream

Эта директива появилась в версии 1.11.2.

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

Синтаксис: variables_hash_max_size размер;
Умолчание:
variables_hash_max_size 1024;
Контекст: stream

Эта директива появилась в версии 1.11.2.

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

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

Модуль 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_имя
TLV, полученный из заголовка протокола PROXY (1.23.2). Имя может быть именем типа 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) - Common Name сертификата
  • ssl_cipher (0x23) - имя используемого шифра
  • ssl_sig_alg (0x24) - алгоритм, используемый для подписи сертификата
  • ssl_key_alg (0x25) - алгоритм публичного ключа

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

  • ssl_verify - результат проверки клиентского сертификата: 0, если клиент предоставил сертификат и он был успешно верифицирован, либо ненулевое значение

Протокол 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_local
локальное время в Common Log Format