Mercurial > hg > nginx-site
view xml/ru/docs/stream/ngx_stream_core_module.xml @ 3077:07f4d29a90c0
Renamed documentation page.
author | Maxim Dounin <mdounin@mdounin.ru> |
---|---|
date | Tue, 09 Apr 2024 18:21:14 +0300 |
parents | 9eadb98ec770 |
children |
line wrap: on
line source
<?xml version="1.0"?> <!-- Copyright (C) Nginx, Inc. --> <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> <module name="Модуль ngx_stream_core_module" link="/ru/docs/stream/ngx_stream_core_module.html" lang="ru" rev="38"> <section id="summary"> <para> Модуль <literal>ngx_stream_core_module</literal> доступен начиная с версии 1.9.0. По умолчанию этот модуль не собирается, его сборку необходимо разрешить с помощью конфигурационного параметра <literal>--with-stream</literal>. </para> </section> <section id="example" name="Пример конфигурации"> <para> <example> 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; } } </example> </para> </section> <section id="directives" name="Директивы"> <directive name="listen"> <syntax> <value>адрес</value>:<value>порт</value> [<literal>ssl</literal>] [<literal>udp</literal>] [<literal>proxy_protocol</literal>] [<literal>fastopen</literal>=<value>число</value>] [<literal>backlog</literal>=<value>число</value>] [<literal>rcvbuf</literal>=<value>размер</value>] [<literal>sndbuf</literal>=<value>размер</value>] [<literal>bind</literal>] [<literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal>] [<literal>reuseport</literal>] [<literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>]]</syntax> <default/> <context>server</context> <para> Задаёт <value>адрес</value> и <value>порт</value> для сокета, на котором сервер будет принимать соединения. Можно указать только порт. Кроме того, адрес может быть именем хоста, например: <example> listen 127.0.0.1:12345; listen *:12345; listen 12345; # то же, что и *:12345 listen localhost:12345; </example> IPv6-адреса задаются в квадратных скобках: <example> listen [::1]:12345; listen [::]:12345; </example> UNIX-сокеты задаются префиксом “<literal>unix:</literal>” <example> listen unix:/var/run/nginx.sock; </example> </para> <para id="listen_port_range"> Диапазоны портов (1.15.10) задаются при помощи указания первого и последнего порта через дефис: <example> listen 127.0.0.1:12345-12399; listen 12345-12399; </example> </para> <para> Параметр <literal>ssl</literal> указывает на то, что все соединения, принимаемые на данном порту, должны работать в режиме SSL. </para> <para id="udp"> Параметр <literal>udp</literal> конфигурирует слушающий сокет для работы с датаграммами (1.9.13). Для обработки пакетов с одного адреса и порта в рамках одной сессии необходимо также указывать параметр <link id="reuseport"><literal>reuseport</literal></link>. </para> <para id="proxy_protocol"> Параметр <literal>proxy_protocol</literal> (1.11.4) указывает на то, что все соединения, принимаемые на данном порту, должны использовать <link url="http://www.haproxy.org/download/1.8/doc/proxy-protocol.txt">протокол PROXY</link>. <note> Протокол PROXY версии 2 поддерживается начиная с версии 1.13.11. </note> </para> <para> В директиве <literal>listen</literal> можно также указать несколько дополнительных параметров, специфичных для связанных с сокетами системных вызовов. <list type="tag"> <tag-name> <literal>fastopen</literal>=<value>число</value> </tag-name> <tag-desc> включает “<link url="http://en.wikipedia.org/wiki/TCP_Fast_Open">TCP Fast Open</link>” для слушающего сокета (1.21.0) и <link url="https://datatracker.ietf.org/doc/html/rfc7413#section-5.1">ограничивает</link> максимальную длину очереди соединений, которые ещё не завершили процесс three-way handshake. <note> Не включайте “TCP Fast Open”, не убедившись, что сервер может адекватно обрабатывать многократное получение <link url="https://datatracker.ietf.org/doc/html/rfc7413#section-6.1"> одного и того же SYN-пакета с данными</link>. </note> </tag-desc> <tag-name> <literal>backlog</literal>=<value>число</value> </tag-name> <tag-desc> задаёт параметр <literal>backlog</literal> в вызове <c-func>listen</c-func>, который ограничивает максимальный размер очереди ожидающих приёма соединений (1.9.2). По умолчанию <literal>backlog</literal> устанавливается равным -1 для FreeBSD, DragonFly BSD и macOS, и 511 для других платформ. </tag-desc> <tag-name> <literal>rcvbuf</literal>=<value>размер</value> </tag-name> <tag-desc> задаёт размер буфера приёма (параметр <c-def>SO_RCVBUF</c-def>) для слушающего сокета (1.11.13). </tag-desc> <tag-name> <literal>sndbuf</literal>=<value>размер</value> </tag-name> <tag-desc> задаёт размер буфера передачи (параметр <c-def>SO_SNDBUF</c-def>) для слушающего сокета (1.11.13). </tag-desc> <tag-name> <literal>bind</literal> </tag-name> <tag-desc> параметр указывает, что для данной пары <value>адрес</value>:<value>порт</value> нужно делать <c-func>bind</c-func> отдельно. Это нужно потому, что если описаны несколько директив <literal>listen</literal> с одинаковым портом, но разными адресами, и одна из директив <literal>listen</literal> слушает на всех адресах для данного порта (<literal>*:</literal><value>порт</value>), то nginx сделает <c-func>bind</c-func> только на <literal>*:</literal><value>порт</value>. Необходимо заметить, что в этом случае для определения адреса, на которой пришло соединение, делается системный вызов <c-func>getsockname</c-func>. Если же используются параметры <literal>backlog</literal>, <literal>rcvbuf</literal>, <literal>sndbuf</literal>, <literal>ipv6only</literal>, <literal>reuseport</literal> или <literal>so_keepalive</literal>, то для данной пары <value>адрес</value>:<value>порт</value> всегда делается отдельный вызов <c-func>bind</c-func>. </tag-desc> <tag-name> <literal>ipv6only</literal>=<literal>on</literal>|<literal>off</literal> </tag-name> <tag-desc> этот параметр определяет (через параметр сокета <c-def>IPV6_V6ONLY</c-def>), будет ли слушающий на wildcard-адресе <literal>[::]</literal> IPv6-сокет принимать только IPv6-соединения, или же одновременно IPv6- и IPv4-соединения. По умолчанию параметр включён. Установить его можно только один раз на старте. </tag-desc> <tag-name id="reuseport"> <literal>reuseport</literal> </tag-name> <tag-desc> этот параметр (1.9.1) указывает, что нужно создавать отдельный слушающий сокет для каждого рабочего процесса (через параметр сокета <c-def>SO_REUSEPORT</c-def> для Linux 3.9+ и DragonFly BSD или <c-def>SO_REUSEPORT_LB</c-def> для FreeBSD 12+), позволяя ядру распределять входящие соединения между рабочими процессами. В настоящий момент это работает только на Linux 3.9+, DragonFly BSD и FreeBSD 12+ (1.15.1). <note> Ненадлежащее использование параметра может быть <link url="http://man7.org/linux/man-pages/man7/socket.7.html">небезопасно</link>. </note> </tag-desc> <tag-name> <literal>so_keepalive</literal>=<literal>on</literal>|<literal>off</literal>|[<value>keepidle</value>]:[<value>keepintvl</value>]:[<value>keepcnt</value>] </tag-name> <tag-desc> этот параметр конфигурирует для слушающего сокета поведение “TCP keepalive”. Если этот параметр опущен, то для сокета будут действовать настройки операционной системы. Если он установлен в значение “<literal>on</literal>”, то для сокета включается параметр <c-def>SO_KEEPALIVE</c-def>. Если он установлен в значение “<literal>off</literal>”, то для сокета параметр <c-def>SO_KEEPALIVE</c-def> выключается. Некоторые операционные системы поддерживают настройку параметров “TCP keepalive” на уровне сокета посредством параметров <c-def>TCP_KEEPIDLE</c-def>, <c-def>TCP_KEEPINTVL</c-def> и <c-def>TCP_KEEPCNT</c-def>. На таких системах (в настоящий момент это Linux 2.4+, NetBSD 5+ и FreeBSD 9.0-STABLE) их можно сконфигурировать с помощью параметров <value>keepidle</value>, <value>keepintvl</value> и <value>keepcnt</value>. Один или два параметра могут быть опущены, в таком случае для соответствующего параметра сокета будут действовать стандартные системные настройки. Например, <example>so_keepalive=30m::10</example> установит таймаут бездействия (<c-def>TCP_KEEPIDLE</c-def>) в 30 минут, для интервала проб (<c-def>TCP_KEEPINTVL</c-def>) будет действовать стандартная системная настройка, а счётчик проб (<c-def>TCP_KEEPCNT</c-def>) будет равен 10. </tag-desc> </list> </para> <para> Разные серверы должны слушать на разных парах <value>адрес</value>:<value>порт</value>. </para> </directive> <directive name="preread_buffer_size"> <syntax><value>размер</value></syntax> <default>16k</default> <context>stream</context> <context>server</context> <appeared-in>1.11.5</appeared-in> <para> Задаёт <value>размер</value> буфера <link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>. </para> </directive> <directive name="preread_timeout"> <syntax><value>время</value></syntax> <default>30s</default> <context>stream</context> <context>server</context> <appeared-in>1.11.5</appeared-in> <para> Задаёт <value>время</value> фазы <link doc="stream_processing.xml" id="preread_phase">предварительного чтения</link>. </para> </directive> <directive name="proxy_protocol_timeout"> <syntax><value>время</value></syntax> <default>30s</default> <context>stream</context> <context>server</context> <appeared-in>1.11.4</appeared-in> <para> Задаёт <value>время</value> для завершения операции чтения заголовка протокола PROXY. Если по истечении этого времени заголовок полностью не получен, соединение закрывается. </para> </directive> <directive name="resolver"> <syntax> <value>адрес</value> ... [<literal>valid</literal>=<value>время</value>] [<literal>ipv4</literal>=<literal>on</literal>|<literal>off</literal>] [<literal>ipv6</literal>=<literal>on</literal>|<literal>off</literal>]</syntax> <default/> <context>stream</context> <context>server</context> <appeared-in>1.11.3</appeared-in> <para> Задаёт серверы DNS, используемые для преобразования имён вышестоящих серверов в адреса, например: <example> resolver 127.0.0.1 [::1]:5353; </example> Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта. Если порт не указан, используется порт 53. Серверы DNS опрашиваются циклически. </para> <para id="resolver_ipv6"> По умолчанию nginx будет искать как IPv4-, так и IPv6-адреса при преобразовании имён в адреса. Если поиск IPv4- или IPv6-адресов нежелателен, можно указать параметр <literal>ipv4=off</literal> (1.23.1) или <literal>ipv6=off</literal>. </para> <para id="resolver_valid"> По умолчанию nginx кэширует ответы, используя значение TTL из ответа. Необязательный параметр <literal>valid</literal> позволяет это переопределить: <example> resolver 127.0.0.1 [::1]:5353 valid=30s; </example> <note> Для предотвращения DNS-спуфинга рекомендуется использовать DNS-серверы в защищённой доверенной локальной сети. </note> </para> </directive> <directive name="resolver_timeout"> <syntax><value>время</value></syntax> <default>30s</default> <context>stream</context> <context>server</context> <appeared-in>1.11.3</appeared-in> <para> Задаёт таймаут для преобразования имени в адрес, например: <example> resolver_timeout 5s; </example> </para> </directive> <directive name="server"> <syntax block="yes"/> <default/> <context>stream</context> <para> Задаёт конфигурацию для сервера. </para> </directive> <directive name="stream"> <syntax block="yes"/> <default/> <context>main</context> <para> Предоставляет контекст конфигурационного файла, в котором указываются директивы stream-сервера. </para> </directive> <directive name="tcp_nodelay"> <syntax><literal>on</literal> | <literal>off</literal></syntax> <default>on</default> <context>stream</context> <context>server</context> <appeared-in>1.9.4</appeared-in> <para> Разрешает или запрещает использование параметра <c-def>TCP_NODELAY</c-def>. Параметр включается как для клиентских соединений, так и для соединений с проксируемыми серверами. </para> </directive> <directive name="variables_hash_bucket_size"> <syntax><value>размер</value></syntax> <default>64</default> <context>stream</context> <appeared-in>1.11.2</appeared-in> <para> Задаёт размер корзины в хэш-таблице переменных. Подробнее настройка хэш-таблиц обсуждается в отдельном <link doc="../hash.xml">документе</link>. </para> </directive> <directive name="variables_hash_max_size"> <syntax><value>размер</value></syntax> <default>1024</default> <context>stream</context> <appeared-in>1.11.2</appeared-in> <para> Задаёт максимальный <value>размер</value> хэш-таблицы переменных. Подробнее настройка хэш-таблиц обсуждается в отдельном <link doc="../hash.xml">документе</link>. </para> </directive> </section> <section id="variables" name="Встроенные переменные"> <para> Модуль <literal>ngx_stream_core_module</literal> поддерживает переменные начиная с версии 1.11.2. <list type="tag"> <tag-name id="var_binary_remote_addr"><var>$binary_remote_addr</var></tag-name> <tag-desc> адрес клиента в бинарном виде, длина значения всегда 4 байта для IPv4-адресов или 16 байт для IPv6-адресов </tag-desc> <tag-name id="var_bytes_received"><var>$bytes_received</var></tag-name> <tag-desc> число байт, полученных от клиента (1.11.4) </tag-desc> <tag-name id="var_bytes_sent"><var>$bytes_sent</var></tag-name> <tag-desc> число байт, переданных клиенту </tag-desc> <tag-name id="var_connection"><var>$connection</var></tag-name> <tag-desc> порядковый номер соединения </tag-desc> <tag-name id="var_hostname"><var>$hostname</var></tag-name> <tag-desc> имя хоста </tag-desc> <tag-name id="var_msec"><var>$msec</var></tag-name> <tag-desc> текущее время в секундах с точностью до миллисекунд </tag-desc> <tag-name id="var_nginx_version"><var>$nginx_version</var></tag-name> <tag-desc> версия nginx </tag-desc> <tag-name id="var_pid"><var>$pid</var></tag-name> <tag-desc> номер (PID) рабочего процесса </tag-desc> <tag-name id="var_protocol"><var>$protocol</var></tag-name> <tag-desc> протокол, используемый для работы с клиентом: <literal>TCP</literal> или <literal>UDP</literal> (1.11.4) </tag-desc> <tag-name id="var_proxy_protocol_addr"><var>$proxy_protocol_addr</var></tag-name> <tag-desc> адрес клиента, полученный из заголовка протокола PROXY (1.11.4) <para> Протокол PROXY должен быть предварительно включён при помощи установки параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>. </para> </tag-desc> <tag-name id="var_proxy_protocol_port"><var>$proxy_protocol_port</var></tag-name> <tag-desc> порт клиента, полученный из заголовка протокола PROXY (1.11.4) <para> Протокол PROXY должен быть предварительно включён при помощи установки параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>. </para> </tag-desc> <tag-name id="var_proxy_protocol_server_addr"><var>$proxy_protocol_server_addr</var></tag-name> <tag-desc> адрес сервера, полученный из заголовка протокола PROXY (1.17.6) <para> Протокол PROXY должен быть предварительно включён при помощи установки параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>. </para> </tag-desc> <tag-name id="var_proxy_protocol_server_port"><var>$proxy_protocol_server_port</var></tag-name> <tag-desc> порт сервера, полученный из заголовка протокола PROXY (1.17.6) <para> Протокол PROXY должен быть предварительно включён при помощи установки параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>. </para> </tag-desc> <tag-name id="var_proxy_protocol_tlv_"><var>$proxy_protocol_tlv_</var><value>имя</value></tag-name> <tag-desc> TLV, полученный из заголовка протокола PROXY (1.23.2). <literal>Имя</literal> может быть именем типа TLV или его числовым значением. В последнем случае значение задаётся в шестнадцатеричном виде и должно начинаться с <literal>0x</literal>: <example> $proxy_protocol_tlv_alpn $proxy_protocol_tlv_0x01 </example> SSL TLV могут также быть доступны как по имени типа TLV, так и по его числовому значению, оба должны начинаться с <literal>ssl_</literal>: <example> $proxy_protocol_tlv_ssl_version $proxy_protocol_tlv_ssl_0x21 </example> <para> Поддерживаются следующие имена типов TLV: <list type="bullet"> <listitem> <literal>alpn</literal> (<literal>0x01</literal>)— протокол более высокого уровня, используемый поверх соединения </listitem> <listitem> <literal>authority</literal> (<literal>0x02</literal>)— значение имени хоста, передаваемое клиентом </listitem> <listitem> <literal>unique_id</literal> (<literal>0x05</literal>)— уникальный идентификатор соединения </listitem> <listitem> <literal>netns</literal> (<literal>0x30</literal>)— имя пространства имён </listitem> <listitem> <literal>ssl</literal> (<literal>0x20</literal>)— структура SSL TLV в бинарном виде </listitem> </list> </para> <para> Поддерживаются следующие имена типов SSL TLV: <list type="bullet"> <listitem> <literal>ssl_version</literal> (<literal>0x21</literal>)— версия SSL, используемая в клиентском соединении </listitem> <listitem> <literal>ssl_cn</literal> (<literal>0x22</literal>)— Common Name сертификата </listitem> <listitem> <literal>ssl_cipher</literal> (<literal>0x23</literal>)— имя используемого шифра </listitem> <listitem> <literal>ssl_sig_alg</literal> (<literal>0x24</literal>)— алгоритм, используемый для подписи сертификата </listitem> <listitem> <literal>ssl_key_alg</literal> (<literal>0x25</literal>)— алгоритм публичного ключа </listitem> </list> </para> <para> Также поддерживается следующее специальное имя типа SSL TLV: <list type="bullet"> <listitem> <literal>ssl_verify</literal>— результат проверки клиентского сертификата: <literal>0</literal>, если клиент предоставил сертификат и он был успешно верифицирован, либо ненулевое значение </listitem> </list> </para> <para> Протокол PROXY должен быть предварительно включён при помощи установки параметра <literal>proxy_protocol</literal> в директиве <link id="listen"/>. </para> </tag-desc> <tag-name id="var_remote_addr"><var>$remote_addr</var></tag-name> <tag-desc> адрес клиента </tag-desc> <tag-name id="var_remote_port"><var>$remote_port</var></tag-name> <tag-desc> порт клиента </tag-desc> <tag-name id="var_server_addr"><var>$server_addr</var></tag-name> <tag-desc> адрес сервера, принявшего соединение <para> Получение значения этой переменной обычно требует одного системного вызова. Чтобы избежать системного вызова, в директивах <link id="listen"/> следует указывать адреса и использовать параметр <literal>bind</literal>. </para> </tag-desc> <tag-name id="var_server_port"><var>$server_port</var></tag-name> <tag-desc> порт сервера, принявшего соединение </tag-desc> <tag-name id="var_session_time"><var>$session_time</var></tag-name> <tag-desc> длительность сессии в секундах с точностью до миллисекунд (1.11.4); </tag-desc> <tag-name id="var_status"><var>$status</var></tag-name> <tag-desc> статус сессии (1.11.4), может принимать одно из следующих значений: <list type="tag"> <tag-name><literal>200</literal></tag-name> <tag-desc> сессия завершена успешно </tag-desc> <tag-name><literal>400</literal></tag-name> <tag-desc> невозможно разобрать данные, полученные от клиента, например заголовок <link id="proxy_protocol">протокола PROXY</link> </tag-desc> <tag-name><literal>403</literal></tag-name> <tag-desc> доступ запрещён, например при ограничении доступа для <link doc="ngx_stream_access_module.xml">определённых адресов клиентов</link> </tag-desc> <tag-name><literal>500</literal></tag-name> <tag-desc> внутренняя ошибка сервера </tag-desc> <tag-name><literal>502</literal></tag-name> <tag-desc> плохой шлюз, например если невозможно выбрать сервер группы или сервер недоступен </tag-desc> <tag-name><literal>503</literal></tag-name> <tag-desc> сервис недоступен, например при ограничении по <link doc="ngx_stream_limit_conn_module.xml">числу соединений</link> </tag-desc> </list> </tag-desc> <tag-name id="var_time_iso8601"><var>$time_iso8601</var></tag-name> <tag-desc> локальное время в формате по стандарту ISO 8601 </tag-desc> <tag-name id="var_time_local"><var>$time_local</var></tag-name> <tag-desc> локальное время в Common Log Format </tag-desc> </list> </para> </section> </module>