Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_hc_module.xml @ 1947:6b6d0e844bf7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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 xml/en/docs/stream/ngx_stream_upstream_module.xml@a58b35cc0823
children 25962922969a
comparison
equal deleted inserted replaced
1946:37df1535ea91 1947:6b6d0e844bf7
1 <?xml version="1.0"?>
2
3 <!--
4 Copyright (C) Nginx, Inc.
5 -->
6
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
8
9 <module name="Module ngx_stream_upstream_hc_module"
10 link="/en/docs/stream/ngx_stream_upstream_hc_module.html"
11 lang="en"
12 rev="1">
13
14 <section id="summary">
15
16 <para>
17 The <literal>ngx_stream_upstream_hc_module</literal> module (1.9.0)
18 allows enabling periodic health checks of the servers in a
19 <link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>.
20 The server group must reside in the
21 <link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>.
22 </para>
23
24 <para>
25 <note>
26 This module is available as part of our
27 <commercial_version>commercial subscription</commercial_version>.
28 </note>
29 </para>
30
31 </section>
32
33
34 <section id="example" name="Example Configuration">
35
36 <para>
37 <example>
38 upstream tcp {
39 zone upstream_tcp 64k;
40
41 server backend1.example.com:12345 weight=5;
42 server backend2.example.com:12345 fail_timeout=5s slow_start=30s;
43 server 192.0.2.1:12345 max_fails=3;
44
45 server backup1.example.com:12345 backup;
46 server backup2.example.com:12345 backup;
47 }
48
49 server {
50 listen 12346;
51 proxy_pass tcp;
52 health_check;
53 }
54 </example>
55 </para>
56
57 </section>
58
59
60 <section id="directives" name="Directives">
61
62 <directive name="health_check">
63 <syntax>[<value>parameters</value>]</syntax>
64 <default/>
65 <context>server</context>
66
67 <para>
68 Enables periodic health checks of the servers in a
69 <link doc="ngx_stream_upstream_module.xml" id="upstream">group</link>.
70 </para>
71
72 <para>
73 The following optional parameters are supported:
74 <list type="tag">
75
76 <tag-name id="interval">
77 <literal>interval</literal>=<value>time</value>
78 </tag-name>
79 <tag-desc>
80 sets the interval between two consecutive health checks,
81 by default, 5 seconds.
82 </tag-desc>
83
84 <tag-name id="health_check_jitter">
85 <literal>jitter</literal>=<value>time</value>
86 </tag-name>
87 <tag-desc>
88 sets the time within which
89 each health check will be randomly delayed,
90 by default, there is no delay.
91 </tag-desc>
92
93 <tag-name id="fails">
94 <literal>fails</literal>=<value>number</value>
95 </tag-name>
96 <tag-desc>
97 sets the number of consecutive failed health checks of a particular server
98 after which this server will be considered unhealthy,
99 by default, 1.
100 </tag-desc>
101
102 <tag-name id="passes">
103 <literal>passes</literal>=<value>number</value>
104 </tag-name>
105 <tag-desc>
106 sets the number of consecutive passed health checks of a particular server
107 after which the server will be considered healthy,
108 by default, 1.
109 </tag-desc>
110
111 <tag-name id="health_check_mandatory">
112 <literal>mandatory</literal>
113 </tag-name>
114 <tag-desc>
115 sets the initial “checking” state for a server
116 until the first health check is completed (1.11.7).
117 If the parameter is not specified,
118 the server will be initially considered healthy.
119 </tag-desc>
120
121 <tag-name id="hc_match">
122 <literal>match</literal>=<value>name</value>
123 </tag-name>
124 <tag-desc>
125 specifies the <literal>match</literal> block configuring the tests that a
126 successful connection should pass in order for a health check to pass.
127 By default, for TCP, only the ability
128 to establish a TCP connection with the server is checked.
129 For <link id="health_check_udp">UDP</link>, the absence of
130 ICMP “<literal>Destination Unreachable</literal>” message is expected
131 in reply to the sent string “<literal>nginx health check</literal>”.
132 <note>
133 Prior to version 1.11.7, by default, UDP health check
134 required a <link id="hc_match">match</link> block with the
135 <link id="match_send">send</link> and <link id="match_expect">expect</link>
136 parameters.
137 </note>
138 </tag-desc>
139
140 <tag-name id="health_check_port">
141 <literal>port</literal>=<value>number</value>
142 </tag-name>
143 <tag-desc>
144 defines the port used when connecting to a server
145 to perform a health check (1.9.7).
146 By default, equals the
147 <link doc="ngx_stream_upstream_module.xml" id="server"/> port.
148 </tag-desc>
149
150 <tag-name id="health_check_udp">
151 <literal>udp</literal>
152 </tag-name>
153 <tag-desc>
154 specifies that the <literal>UDP</literal> protocol should be used for
155 health checks instead of the default <literal>TCP</literal> protocol (1.9.13).
156 </tag-desc>
157
158 </list>
159 </para>
160
161 <para>
162 For example,
163 <example>
164 server {
165 proxy_pass backend;
166 health_check;
167 }
168 </example>
169 will check the ability to establish a TCP connection to each server
170 in the <literal>backend</literal> group every five seconds.
171 When a connection to the server cannot be established,
172 the health check will fail, and the server will
173 be considered unhealthy.
174 Client connections are not passed to unhealthy servers
175 and servers in the “checking” state.
176 </para>
177
178 <para>
179 Health checks can also be configured to test data obtained from the server.
180 Tests are configured separately using the <link id="match"/> directive
181 and referenced in the <literal>match</literal> parameter.
182 </para>
183
184 <para>
185 The server group must reside in the
186 <link doc="ngx_stream_upstream_module.xml" id="zone">shared memory</link>.
187 </para>
188
189 <para>
190 If several health checks are defined for the same group of servers,
191 a single failure of any check will make the corresponding server be
192 considered unhealthy.
193 </para>
194
195 </directive>
196
197
198 <directive name="health_check_timeout">
199 <syntax><value>timeout</value></syntax>
200 <default>5s</default>
201 <context>stream</context>
202 <context>server</context>
203
204 <para>
205 Overrides the
206 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
207 value for health checks.
208 </para>
209
210 </directive>
211
212
213 <directive name="match">
214 <syntax block="yes"><value>name</value> </syntax>
215 <default/>
216 <context>stream</context>
217
218 <para>
219 Defines the named test set used to verify server responses to health checks.
220 </para>
221
222 <para>
223 The following parameters can be configured:
224 <list type="tag">
225
226 <tag-name id="match_send">
227 <literal>send</literal> <value>string</value>;
228 </tag-name>
229 <tag-desc>
230 sends a <value>string</value> to the server;
231 </tag-desc>
232
233 <tag-name id="match_expect">
234 <literal>expect</literal> <value>string</value> |
235 <literal>~</literal> <value>regex</value>;
236 </tag-name>
237 <tag-desc>
238 a literal string (1.9.12) or a regular expression
239 that the data obtained from the server should match.
240 The regular expression is specified with the preceding
241 “<literal>~*</literal>” modifier (for case-insensitive matching), or the
242 “<literal>~</literal>” modifier (for case-sensitive matching).
243 </tag-desc>
244
245 </list>
246 Both <literal>send</literal> and <literal>expect</literal> parameters
247 can contain hexadecimal literals with the prefix “<literal>\x</literal>”
248 followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12).
249 </para>
250
251 <para>
252 Health check is passed if:
253 <list type="bullet">
254 <listitem>
255 the TCP connection was successfully established;
256 </listitem>
257
258 <listitem>
259 the <value>string</value> from the <literal>send</literal> parameter,
260 if specified, was sent;
261 </listitem>
262
263 <listitem>
264 the data obtained from the server matched the string or regular expression
265 from the <literal>expect</literal> parameter, if specified;
266 </listitem>
267
268 <listitem>
269 the time elapsed does not exceed the value specified
270 in the <link id="health_check_timeout"/> directive.
271 </listitem>
272
273 </list>
274 </para>
275
276 <para>
277 Example:
278 <example>
279 upstream backend {
280 zone upstream_backend 10m;
281 server 127.0.0.1:12345;
282 }
283
284 match http {
285 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
286 expect ~ "200 OK";
287 }
288
289 server {
290 listen 12346;
291 proxy_pass backend;
292 health_check match=http;
293 }
294 </example>
295 </para>
296
297 <para>
298 <note>
299 Only the first
300 <link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>
301 bytes of data obtained from the server are examined.
302 </note>
303 </para>
304
305 </directive>
306
307 </section>
308
309 </module>