<?xml version="1.0"?>

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

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

<module name="Module ngx_stream_upstream_hc_module"
        link="/en/docs/stream/ngx_stream_upstream_hc_module.html"
        lang="en"
        rev="2">

<section id="summary">

<para>
The <literal>ngx_stream_upstream_hc_module</literal> module (1.9.0)
allows enabling periodic health checks of the servers in a
<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>.
The server group must reside in the
<link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>.
</para>

<para>
If a health check fails, the server will be considered unhealthy.
If several health checks are defined for the same group of servers,
a single failure of any check will make the corresponding server be
considered unhealthy.
Client connections are not passed to unhealthy servers
and servers in the “checking” state.
</para>

<para>
<note>
This module is available as part of our
<commercial_version>commercial subscription</commercial_version>.
</note>
</para>

</section>


<section id="example" name="Example Configuration">

<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>
With this configuration, nginx
will check the ability to establish a TCP connection to each server
in the <literal>tcp</literal> group every five seconds.
When a connection to the server cannot be established,
the health check will fail, and the server will
be considered unhealthy.
</para>

<para>
Health checks can also be configured to test data obtained from the server.
Tests are configured separately using the <link id="match"/> directive
and referenced in the <literal>match</literal> parameter
of the <link id="health_check"/> directive.
</para>

</section>


<section id="directives" name="Directives">

<directive name="health_check">
<syntax>[<value>parameters</value>]</syntax>
<default/>
<context>server</context>

<para>
Enables periodic health checks of the servers in a
<link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>.
</para>

<para>
The following optional parameters are supported:
<list type="tag">

<tag-name id="interval">
<literal>interval</literal>=<value>time</value>
</tag-name>
<tag-desc>
sets the interval between two consecutive health checks,
by default, 5 seconds.
</tag-desc>

<tag-name id="health_check_jitter">
<literal>jitter</literal>=<value>time</value>
</tag-name>
<tag-desc>
sets the time within which
each health check will be randomly delayed,
by default, there is no delay.
</tag-desc>

<tag-name id="fails">
<literal>fails</literal>=<value>number</value>
</tag-name>
<tag-desc>
sets the number of consecutive failed health checks of a particular server
after which this server will be considered unhealthy,
by default, 1.
</tag-desc>

<tag-name id="passes">
<literal>passes</literal>=<value>number</value>
</tag-name>
<tag-desc>
sets the number of consecutive passed health checks of a particular server
after which the server will be considered healthy,
by default, 1.
</tag-desc>

<tag-name id="health_check_mandatory">
<literal>mandatory</literal>
</tag-name>
<tag-desc>
sets the initial “checking” state for a server
until the first health check is completed (1.11.7).
If the parameter is not specified,
the server will be initially considered healthy.
</tag-desc>

<tag-name id="hc_match">
<literal>match</literal>=<value>name</value>
</tag-name>
<tag-desc>
specifies the <literal>match</literal> block configuring the tests that a
successful connection should pass in order for a health check to pass.
By default, for TCP, only the ability
to establish a TCP connection with the server is checked.
For <link id="health_check_udp">UDP</link>, the absence of
ICMP “<literal>Destination Unreachable</literal>” message is expected
in reply to the sent string “<literal>nginx health check</literal>”.
<note>
Prior to version 1.11.7, by default, UDP health check
required a <link id="hc_match">match</link> block with the
<link id="match_send">send</link> and <link id="match_expect">expect</link>
parameters.
</note>
</tag-desc>

<tag-name id="health_check_port">
<literal>port</literal>=<value>number</value>
</tag-name>
<tag-desc>
defines the port used when connecting to a server
to perform a health check (1.9.7).
By default, equals the
<link doc="ngx_stream_upstream_module.xml" id="server"/> port.
</tag-desc>

<tag-name id="health_check_udp">
<literal>udp</literal>
</tag-name>
<tag-desc>
specifies that the <literal>UDP</literal> protocol should be used for
health checks instead of the default <literal>TCP</literal> protocol (1.9.13).
</tag-desc>

</list>
</para>

</directive>


<directive name="health_check_timeout">
<syntax><value>timeout</value></syntax>
<default>5s</default>
<context>stream</context>
<context>server</context>

<para>
Overrides the
<link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
value for health checks.
</para>

</directive>


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

<para>
Defines the named test set used to verify server responses to health checks.
</para>

<para>
The following parameters can be configured:
<list type="tag">

<tag-name id="match_send">
<literal>send</literal> <value>string</value>;
</tag-name>
<tag-desc>
sends a <value>string</value> to the server;
</tag-desc>

<tag-name id="match_expect">
<literal>expect</literal> <value>string</value> |
<literal>~</literal> <value>regex</value>;
</tag-name>
<tag-desc>
a literal string (1.9.12) or a regular expression
that the data obtained from the server should match.
The regular expression is specified with the preceding
“<literal>~*</literal>” modifier (for case-insensitive matching), or the
“<literal>~</literal>” modifier (for case-sensitive matching).
</tag-desc>

</list>
Both <literal>send</literal> and <literal>expect</literal> parameters
can contain hexadecimal literals with the prefix “<literal>\x</literal>”
followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12).
</para>

<para>
Health check is passed if:
<list type="bullet">
<listitem>
the TCP connection was successfully established;
</listitem>

<listitem>
the <value>string</value> from the <literal>send</literal> parameter,
if specified, was sent;
</listitem>

<listitem>
the data obtained from the server matched the string or regular expression
from the <literal>expect</literal> parameter, if specified;
</listitem>

<listitem>
the time elapsed does not exceed the value specified
in the <link id="health_check_timeout"/> directive.
</listitem>

</list>
</para>

<para>
Example:
<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>
Only the first
<link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>
bytes of data obtained from the server are examined.
</note>
</para>

</directive>

</section>

</module>