<?xml version="1.0"?>

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

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

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

<section id="summary">

<para>
The <literal>ngx_http_upstream_hc_module</literal> module
allows enabling periodic health checks of the servers in a
<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
referenced in the surrounding location.
The server group must reside in the
<link doc="ngx_http_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 requests are not passed to unhealthy servers
and servers in the “checking” state.
</para>

<para>
<note>
Please note that most of the variables will have empty values
when used with health checks.
</note>
</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 dynamic {
    zone upstream_dynamic 64k;

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

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

server {
    location / {
        proxy_pass http://dynamic;
        health_check;
    }
}
</example>
With this configuration, nginx will send “<literal>/</literal>” requests to each
server in the <literal>backend</literal> group every five seconds.
If any communication error or timeout occurs, or a
proxied server responds with the status code other than
2xx or 3xx, the health check will fail, and the server will
be considered unhealthy.
</para>

<para>
Health checks can be configured to test the status code of a response,
presence of certain header fields and their values,
and the body contents.
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:
<example>
http {
    server {
    ...
        location / {
            proxy_pass http://backend;
            health_check match=welcome;
        }
    }

    match welcome {
        status 200;
        header Content-Type = text/html;
        body ~ "Welcome to nginx!";
    }
}
</example>
This configuration shows that in order for a health check to pass, the response
to a health check request should succeed, have status 200,
and contain “<literal>Welcome to nginx!</literal>” in the body.
</para>

</section>


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

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

<para>
Enables periodic health checks of the servers in a
<link doc="ngx_http_upstream_module.xml" id="upstream">group</link>
referenced in the surrounding location.
</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="uri">
<literal>uri</literal>=<value>uri</value>
</tag-name>
<tag-desc>
defines the URI used in health check requests,
by default, “<literal>/</literal>”.
</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
response should pass in order for a health check to pass.
By default, the response should have status code 2xx or 3xx.
</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_http_upstream_module.xml" id="server"/> port.
</tag-desc>

</list>
</para>

</directive>


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

<para>
Defines the named test set used to verify responses to health check requests.
</para>

<para>
The following items can be tested in a response:
<list type="tag">

<tag-name><literal>status 200;</literal></tag-name>
<tag-desc>status is 200</tag-desc>

<tag-name><literal>status ! 500;</literal></tag-name>
<tag-desc>status is not 500</tag-desc>

<tag-name><literal>status 200 204;</literal></tag-name>
<tag-desc>status is 200 or 204</tag-desc>

<tag-name><literal>status ! 301 302;</literal></tag-name>
<tag-desc>status is neither 301 nor 302</tag-desc>

<tag-name><literal>status 200-399;</literal></tag-name>
<tag-desc>status is in the range from 200 to 399</tag-desc>

<tag-name><literal>status ! 400-599;</literal></tag-name>
<tag-desc>status is not in the range from 400 to 599</tag-desc>

<tag-name><literal>status 301-303 307;</literal></tag-name>
<tag-desc>status is either 301, 302, 303, or 307</tag-desc>

</list>

<list type="tag">

<tag-name><literal>header Content-Type = text/html;</literal></tag-name>
<tag-desc>
header contains <header>Content-Type</header>
with value <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Content-Type != text/html;</literal></tag-name>
<tag-desc>
header contains <header>Content-Type</header>
with value other than <literal>text/html</literal>
</tag-desc>

<tag-name><literal>header Connection ~ close;</literal></tag-name>
<tag-desc>
header contains <header>Connection</header>
with value matching regular expression <literal>close</literal>
</tag-desc>

<tag-name><literal>header Connection !~ close;</literal></tag-name>
<tag-desc>
header contains <header>Connection</header>
with value not matching regular expression <literal>close</literal>
</tag-desc>

<tag-name><literal>header Host;</literal></tag-name>
<tag-desc>header contains <header>Host</header></tag-desc>

<tag-name><literal>header ! X-Accel-Redirect;</literal></tag-name>
<tag-desc>header lacks <header>X-Accel-Redirect</header></tag-desc>

</list>

<list type="tag">

<tag-name><literal>body ~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
body matches regular expression “<literal>Welcome to nginx!</literal>”
</tag-desc>

<tag-name><literal>body !~ "Welcome to nginx!";</literal></tag-name>
<tag-desc>
body does not match regular expression “<literal>Welcome to nginx!</literal>”
</tag-desc>

</list>
</para>

<para>
If several tests are specified,
the response matches only if it matches all tests.
<note>
Only the first 256k of the response body are examined.
</note>
</para>

<para>
Examples:
<example>
# status is 200, content type is "text/html",
# and body contains "Welcome to nginx!"
match welcome {
    status 200;
    header Content-Type = text/html;
    body ~ "Welcome to nginx!";
}
</example>

<example>
# status is not one of 301, 302, 303, or 307, and header does not have "Refresh:"
match not_redirect {
    status ! 301-303 307;
    header ! Refresh;
}
</example>

<example>
# status ok and not in maintenance mode
match server_ok {
    status 200-399;
    body !~ "maintenance mode";
}
</example>

</para>

</directive>

</section>

</module>