--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/http/ngx_http_upstream_hc_module.xml	Thu Mar 30 21:26:44 2017 +0300
@@ -0,0 +1,348 @@
+<?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="1">
+
+<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.
+</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>
+</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>
+
+<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 doc="ngx_http_upstream_module.xml" 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>
+
+</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>