Mercurial > hg > nginx-site
view xml/en/docs/stream/ngx_stream_upstream_hc_module.xml @ 1949:8f9c685dfabd
Updated IDs in "health_check" directives.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 30 Mar 2017 21:26:44 +0300 |
parents | 25962922969a |
children | ef22a80a2696 |
line wrap: on
line source
<?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="3"> <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="health_check_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="health_check_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="health_check_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="health_check_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>