--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/xml/en/docs/stream/ngx_stream_upstream_hc_module.xml	Fri Mar 24 19:48:53 2017 +0300
@@ -0,0 +1,309 @@
+<?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="1">
+
+<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>
+<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>
+</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="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 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>
+
+<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 doc="ngx_stream_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>
+
+</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>