<?xml version="1.0"?>

<!--
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_stream_upstream_hc_module"
        link="/ru/docs/stream/ngx_stream_upstream_hc_module.html"
        lang="ru"
        rev="6">

<section id="summary">

<para>
Модуль <literal>ngx_stream_upstream_hc_module</literal> (1.9.0)
позволяет активировать периодические проверки работоспособности серверов в
<link doc="ngx_stream_upstream_module.xml" id="upstream">группе</link>.
Группа должна находиться в
<link doc="ngx_stream_upstream_module.xml" id="zone">зоне разделяемой памяти</link>.
</para>

<para>
Если проверка работоспособности была неуспешной,
то сервер признаётся неработоспособным.
Если для группы задано несколько проверок,
то при любой неуспешной проверке соответствующий сервер будет
считаться неработоспособным.
На неработоспособные серверы и серверы в состоянии “checking”
клиентские соединения передаваться не будут.
</para>

<para>
<note>
Модуль доступен как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
upstream tcp {
    zone upstream_tcp 64k;

    server backend1.example.com:12345 weight=5;
    server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
    server 192.0.2.1:12345            max_fails=3;

    server backup1.example.com:12345  backup;
    server backup2.example.com:12345  backup;
}

server {
    listen     12346;
    proxy_pass tcp;
    health_check;
}
</example>
Для каждого сервера группы <literal>tcp</literal>
с интервалом в 5 секунд проверяется возможность установки TCP-соединения.
Если соединение с сервером не может быть установлено,
проверка считается неуспешной и сервер
признаётся неработоспособным.
</para>

<para>
Проверки работоспособности можно настроить для протокола UDP:
<example>
upstream dns_upstream {

    zone   dns_zone 64k;

    server dns1.example.com:53;
    server dns2.example.com:53;
    server dns3.example.com:53;
}

server {
    listen       53 udp;
    proxy_pass   dns_upstream;
    health_check udp;
}
</example>
В этом случае проверяется отсутствие
сообщения ICMP “<literal>Destination Unreachable</literal>”
в ответ на отправленную строку “<literal>nginx health check</literal>”.
</para>

<para>
Проверки работоспособности могут тестировать данные, полученные от сервера.
Тесты настраиваются отдельно при помощи директивы <link id="match"/>
и указываются в параметре <literal>match</literal> директивы
<link id="health_check"/>.
</para>

</section>


<section id="directives" name="Директивы">

<directive name="health_check">
<syntax>[<value>параметры</value>]</syntax>
<default/>
<context>server</context>

<para>
Активирует периодические проверки работоспособности серверов в
<link doc="ngx_stream_upstream_hc_module.xml" id="upstream">группе</link>.
</para>

<para>
Могут быть заданы следующие необязательные параметры:
<list type="tag">

<tag-name id="health_check_interval">
<literal>interval</literal>=<value>время</value>
</tag-name>
<tag-desc>
задаёт интервал между двумя последовательными проверками,
по умолчанию 5 секунд.
</tag-desc>

<tag-name id="health_check_jitter">
<literal>jitter</literal>=<value>время</value>
</tag-name>
<tag-desc>
задаёт время, в пределах которого
случайным образом задерживается каждая проверка,
по умолчанию задержки нет.
</tag-desc>

<tag-name id="health_check_fails">
<literal>fails</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт число последовательных неуспешных проверок для определённого сервера,
после которых сервер будет считаться неработоспособным,
по умолчанию 1.
</tag-desc>

<tag-name id="health_check_passes">
<literal>passes</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт число последовательных успешных проверок для определённого сервера,
после которых сервер будет считаться работоспособным,
по умолчанию 1.
</tag-desc>

<tag-name id="health_check_mandatory">
<literal>mandatory</literal> [<literal>persistent</literal>]
</tag-name>
<tag-desc>
<para>
устанавливает исходное состояние “checking” для сервера
до завершения первой проверки работоспособности (1.11.7).
На серверы в состоянии “checking” клиентские соединения передаваться не будут.
Если параметр не указан,
то исходно сервер будет считаться работоспособным.
</para>

<para id="health_check_persistent">
Параметр <literal>persistent</literal> (1.21.1)
устанавливает исходное состояние “up” для сервера после перезагрузки nginx
в случае, если до перезагрузки сервер считался работоспособным.
</para>
</tag-desc>

<tag-name id="health_check_match">
<literal>match</literal>=<value>имя</value>
</tag-name>
<tag-desc>
указывает на блок <literal>match</literal> с условиями, которым должно
удовлетворять соединение, чтобы результат проверки считался успешным.
По умолчанию для TCP проверяется
лишь возможность установки TCP-соединения с сервером,
для <link id="health_check_udp">UDP</link> проверяется отсутствие
сообщения ICMP “<literal>Destination Unreachable</literal>”
в ответ на отправленную строку “<literal>nginx health check</literal>”.
<note>
До версии 1.11.7 по умолчанию для UDP
требовалось наличие блока <link id="hc_match">match</link> с параметрами
<link id="match_send">send</link> и <link id="match_expect">expect</link>.
</note>
</tag-desc>

<tag-name id="health_check_port">
<literal>port</literal>=<value>число</value>
</tag-name>
<tag-desc>
задаёт порт, используемый при подключении к серверу
для проверки его работоспособности (1.9.7).
По умолчанию совпадает с портом
<link doc="ngx_stream_upstream_module.xml" id="server">сервера</link>.
</tag-desc>

<tag-name id="health_check_udp">
<literal>udp</literal>
</tag-name>
<tag-desc>
указывает, что для проверки работоспособности будет использоваться протокол
<literal>UDP</literal>
вместо протокола <literal>TCP</literal>, используемого по умолчанию (1.9.13).
</tag-desc>

</list>
</para>

</directive>


<directive name="health_check_timeout">
<syntax><value>время</value></syntax>
<default>5s</default>
<context>stream</context>
<context>server</context>

<para>
Переопределяет значение
<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
для проверок работоспособности.
</para>

</directive>


<directive name="match">
<syntax block="yes"><value>имя</value> </syntax>
<default/>
<context>stream</context>

<para>
Задаёт именованный набор тестов для для анализа ответов сервера
на запросы проверки работоспособности.
</para>

<para>
Могут быть заданы следующие параметры:
<list type="tag">

<tag-name id="match_send">
<literal>send</literal> <value>строка</value>;
</tag-name>
<tag-desc>
отправляет <value>строку</value> на сервер;
</tag-desc>

<tag-name id="match_expect">
<literal>expect</literal> <value>стока</value> |
<literal>~</literal> <value>regex</value>;
</tag-name>
<tag-desc>
текстовая строка (1.9.12) или регулярное выражение,
которым должны соответствовать данные, полученные с сервера.
Регулярное выражение задаётся либо с модификатором
“<literal>~*</literal>” (для поиска совпадения без учёта регистра символов),
либо с модификатором “<literal>~</literal>” (с учётом регистра).
</tag-desc>

</list>
Параметры <literal>send</literal> и <literal>expect</literal>
могут содержать строки в шестнадцатеричном виде
с префиксом “<literal>\x</literal>”
и последующими двумя шестнадцатеричными цифрами,
например “<literal>\x80</literal>” (1.9.12).
</para>

<para>
Проверка работоспособности считается успешной, если
<list type="bullet">
<listitem>
TCP-соединение успешно установлено;
</listitem>

<listitem>
<value>строка</value> из параметра <literal>send</literal>
была отправлена (если была задана);
</listitem>

<listitem>
данные, полученные от сервера, совпали со строкой или регулярным выражением
из параметра <literal>expect</literal> (если был задан);
</listitem>

<listitem>
истёкшее время не превышает значение, указанное
в директиве <link id="health_check_timeout"/>.
</listitem>

</list>
</para>

<para>
Пример:
<example>
upstream backend {
    zone     upstream_backend 10m;
    server   127.0.0.1:12345;
}

match http {
    send     "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
    expect ~ "200 OK";
}

server {
    listen       12346;
    proxy_pass   backend;
    health_check match=http;
}
</example>
</para>

<para>
<note>
Проверяются лишь первые байты данных
<link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>,
полученные от сервера.
</note>
</para>

</directive>

</section>

</module>