Mercurial > hg > nginx-site
diff xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1947:6b6d0e844bf7
Moved "health_check" and "match" to ngx_stream_upstream_hc_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Fri, 24 Mar 2017 19:48:53 +0300 |
parents | a58b35cc0823 |
children | eb58ee50561d |
line wrap: on
line diff
--- a/xml/en/docs/stream/ngx_stream_upstream_module.xml Thu Mar 30 21:26:44 2017 +0300 +++ b/xml/en/docs/stream/ngx_stream_upstream_module.xml Fri Mar 24 19:48:53 2017 +0300 @@ -9,7 +9,7 @@ <module name="Module ngx_stream_upstream_module" link="/en/docs/stream/ngx_stream_upstream_module.html" lang="en" - rev="24"> + rev="25"> <section id="summary"> @@ -46,7 +46,8 @@ </para> <para> -Dynamically configurable group, +Dynamically configurable group with +periodic <link doc="ngx_stream_upstream_hc_module.xml">health checks</link> is available as part of our <commercial_version>commercial subscription</commercial_version>: <example> @@ -297,7 +298,7 @@ <tag-desc> sets the <value>time</value> during which the server will recover its weight from zero to a nominal value, when unhealthy server becomes -<link id="health_check">healthy</link>, +<link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>, or when the server becomes available after a period of time it was considered <link id="fail_timeout">unavailable</link>. Default value is zero, i.e. slow start is disabled. @@ -491,271 +492,6 @@ </directive> - -<directive name="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>server</context> - -<para> -Enables periodic health checks of the servers in a -<link 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 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> - -<para> -For example, -<example> -server { - proxy_pass backend; - health_check; -} -</example> -will check the ability to establish a TCP connection to each server -in the <literal>backend</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. -Client connections are not passed to unhealthy servers -and servers in the “checking” state. -</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. -</para> - -<para> -The server group must reside in the <link id="zone">shared memory</link>. -</para> - -<para> -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. -</para> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</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> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</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> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - </section>