Модуль ngx_stream_core_module

• Пример конфигурации
• Директивы
• listen
• preread_buffer_size
• preread_timeout
• proxy_protocol_timeout
• resolver
• resolver_timeout
• сервер
• имя_сервера
• server_names_hash_bucket_size
• server_names_hash_max_size
• поток
• 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, или 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).

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

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 разные серверы должны прослушивать разные пары address:port.

Указывает размер буфера предварительной обработки (preread).

Указывает таймаут фазы предварительной обработки (preread).

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

resolver 127.0.0.1 [::1]:5353;

По умолчанию 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-адресе) и именными (основанными на расширении 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). Тип TLV может быть именем типа или его числовым значением. В последнем случае значение задаётся в шестнадцатеричном формате и должно быть префиксровано 0x:

$proxy_protocol_tlv_alpn
$proxy_protocol_tlv_0x01

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

$proxy_protocol_tlv_ssl_version
$proxy_protocol_tlv_ssl_0x21

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

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

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

• 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_local

локальное время в формате Common Log Format