Mercurial > hg > nginx-site
diff xml/en/docs/http/ngx_http_upstream_module.xml @ 1945:88477c5d2751
Moved "health_check" and "match" to ngx_http_upstream_hc_module.
author | Yaroslav Zhuravlev <yar@nginx.com> |
---|---|
date | Thu, 30 Mar 2017 21:26:44 +0300 |
parents | a58b35cc0823 |
children | 5c55b7054b58 |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_upstream_module.xml +++ b/xml/en/docs/http/ngx_http_upstream_module.xml @@ -10,7 +10,7 @@ <module name="Module ngx_http_upstream_module" link="/en/docs/http/ngx_http_upstream_module.html" lang="en" - rev="59"> + rev="60"> <section id="summary"> @@ -49,7 +49,8 @@ server { </para> <para> -Dynamically configurable group, +Dynamically configurable group with +periodic <link doc="ngx_http_upstream_hc_module.xml">health checks</link> is available as part of our <commercial_version>commercial subscription</commercial_version>: <example> @@ -321,7 +322,7 @@ the rest of SRV records are ignored. <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_http_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. @@ -741,302 +742,6 @@ This directive is available as part of o </directive> -<directive name="health_check"> -<syntax>[<value>parameters</value>]</syntax> -<default/> -<context>location</context> - -<para> -Enables periodic health checks of the servers in a -<link 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 id="server"/> port. -</tag-desc> - -</list> -</para> - -<para> -For example, -<example> -location / { - proxy_pass http://backend; - health_check; -} -</example> -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. -Client requests are not passed to unhealthy servers -and servers in the “checking” state. -</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. -For example: -<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, content type “<literal>text/html</literal>”, -and contain “<literal>Welcome to nginx!</literal>” in the body. -</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> -Please note that most of the variables will have empty values -when used with health checks. -</note> -</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>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> - -<para> -<note> -This directive is available as part of our -<commercial_version>commercial subscription</commercial_version>. -</note> -</para> - -</directive> - - <directive name="queue"> <syntax> <value>number</value>