Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1450:f5b5eefc43cb
Updated commercial docs for the upcoming release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 09 Apr 2015 19:18:54 +0300 |
parents | f5dcc23b214f |
children | e69e4dbcc760 |
comparison
equal
deleted
inserted
replaced
1449:c79501e16e26 | 1450:f5b5eefc43cb |
---|---|
7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | 7 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> |
8 | 8 |
9 <module name="Module ngx_stream_upstream_module" | 9 <module name="Module ngx_stream_upstream_module" |
10 link="/en/docs/stream/ngx_stream_upstream_module.html" | 10 link="/en/docs/stream/ngx_stream_upstream_module.html" |
11 lang="en" | 11 lang="en" |
12 rev="4"> | 12 rev="5"> |
13 | 13 |
14 <section id="summary"> | 14 <section id="summary"> |
15 | 15 |
16 <para> | 16 <para> |
17 The <literal>ngx_stream_upstream_module</literal> module (1.7.7) | 17 The <literal>ngx_stream_upstream_module</literal> module (1.7.7) |
32 | 32 |
33 <section id="example" name="Example Configuration"> | 33 <section id="example" name="Example Configuration"> |
34 | 34 |
35 <para> | 35 <para> |
36 <example> | 36 <example> |
37 resolver 10.0.0.1; | |
38 | |
37 upstream <emphasis>backend</emphasis> { | 39 upstream <emphasis>backend</emphasis> { |
40 zone upstream_backend 64k; | |
41 | |
38 hash $remote_addr consistent; | 42 hash $remote_addr consistent; |
39 | 43 |
40 server backend1.example.com:12345 weight=5; | 44 server backend1.example.com:12345 weight=5; |
41 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; | 45 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; |
42 server unix:/tmp/backend3; | 46 server unix:/tmp/backend2; |
47 server backend3.example.com:12345 resolve; | |
43 } | 48 } |
44 | 49 |
45 server { | 50 server { |
46 listen 12346; | 51 listen 12346; |
47 proxy_pass <emphasis>backend</emphasis>; | 52 proxy_pass <emphasis>backend</emphasis>; |
53 health_check; | |
48 } | 54 } |
49 </example> | 55 </example> |
50 </para> | 56 </para> |
51 | 57 |
52 </section> | 58 </section> |
70 Example: | 76 Example: |
71 <example> | 77 <example> |
72 upstream backend { | 78 upstream backend { |
73 server backend1.example.com:12345 weight=5; | 79 server backend1.example.com:12345 weight=5; |
74 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; | 80 server 127.0.0.1:12345 max_fails=3 fail_timeout=30s; |
75 server unix:/tmp/backend3; | 81 server unix:/tmp/backend2; |
82 server backend3.example.com:12345 resolve; | |
76 | 83 |
77 server backup1.example.com:12345 backup; | 84 server backup1.example.com:12345 backup; |
78 } | 85 } |
79 </example> | 86 </example> |
80 </para> | 87 </para> |
177 limits the maximum <value>number</value> of simultaneous connections to the | 184 limits the maximum <value>number</value> of simultaneous connections to the |
178 proxied server. | 185 proxied server. |
179 Default value is zero, meaning there is no limit. | 186 Default value is zero, meaning there is no limit. |
180 </tag-desc> | 187 </tag-desc> |
181 | 188 |
189 <tag-name id="resolve"> | |
190 <literal>resolve</literal> | |
191 </tag-name> | |
192 <tag-desc> | |
193 monitors changes of the IP addresses | |
194 that correspond to a domain name of the server, | |
195 and automatically modifies the upstream configuration | |
196 without the need of restarting nginx (1.7.10). | |
197 <para> | |
198 In order for this parameter to work, | |
199 the <link doc="ngx_stream_core_module.xml" id="resolver"/> directive | |
200 must be specified in the | |
201 <link doc="ngx_stream_core_module.xml" id="stream"/> block. | |
202 Example: | |
203 <example> | |
204 stream { | |
205 resolver 10.0.0.1; | |
206 | |
207 upstream u { | |
208 zone ...; | |
209 ... | |
210 server example.com:12345 resolve; | |
211 } | |
212 } | |
213 </example> | |
214 </para> | |
215 </tag-desc> | |
216 | |
182 <tag-name id="slow_start"> | 217 <tag-name id="slow_start"> |
183 <literal>slow_start</literal>=<value>time</value> | 218 <literal>slow_start</literal>=<value>time</value> |
184 </tag-name> | 219 </tag-name> |
185 <tag-desc> | 220 <tag-desc> |
186 sets the <value>time</value> during which the server will recover its weight | 221 sets the <value>time</value> during which the server will recover its weight |
197 <note> | 232 <note> |
198 If there is only a single server in a group, <literal>max_fails</literal>, | 233 If there is only a single server in a group, <literal>max_fails</literal>, |
199 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters | 234 <literal>fail_timeout</literal> and <literal>slow_start</literal> parameters |
200 are ignored, and such a server will never be considered unavailable. | 235 are ignored, and such a server will never be considered unavailable. |
201 </note> | 236 </note> |
237 </para> | |
238 | |
239 </directive> | |
240 | |
241 | |
242 <directive name="zone"> | |
243 <syntax><value>name</value> <value>size</value></syntax> | |
244 <default/> | |
245 <context>upstream</context> | |
246 <appeared-in>1.7.10</appeared-in> | |
247 | |
248 <para> | |
249 Defines the <value>name</value> and <value>size</value> of the shared | |
250 memory zone that keeps the group’s configuration and run-time state that are | |
251 shared between worker processes. | |
252 Such groups allow changing the group membership | |
253 or modifying the settings of a particular server | |
254 without the need of restarting nginx. | |
255 The configuration is accessible via a special location | |
256 handled by | |
257 <link doc="../http/ngx_http_upstream_conf_module.xml" id="upstream_conf"/>. | |
202 </para> | 258 </para> |
203 | 259 |
204 </directive> | 260 </directive> |
205 | 261 |
206 | 262 |
251 weighted round-robin balancing method. | 307 weighted round-robin balancing method. |
252 </para> | 308 </para> |
253 | 309 |
254 </directive> | 310 </directive> |
255 | 311 |
312 | |
313 <directive name="least_time"> | |
314 <syntax><literal>connect</literal> | | |
315 <literal>first_byte</literal> | | |
316 <literal>last_byte</literal></syntax> | |
317 <default/> | |
318 <context>upstream</context> | |
319 <appeared-in>1.7.11</appeared-in> | |
320 | |
321 <para> | |
322 Specifies that a group should use a load balancing method where a connection | |
323 is passed to the server with the least average time and | |
324 least number of active connections, taking into account weights of servers. | |
325 If there are several such servers, they are tried in turn using a | |
326 weighted round-robin balancing method. | |
327 </para> | |
328 | |
329 <para> | |
330 If the <literal>connect</literal> parameter is specified, | |
331 time to connect to the upstream server is used. | |
332 If the <literal>first_byte</literal> parameter is specified, | |
333 time to receive the first byte of data is used. | |
334 If the <literal>last_byte</literal> is specified, | |
335 time to receive the last byte of data is used. | |
336 </para> | |
337 | |
338 </directive> | |
339 | |
340 | |
341 <directive name="health_check"> | |
342 <syntax>[<value>parameters</value>]</syntax> | |
343 <default/> | |
344 <context>server</context> | |
345 <appeared-in>1.7.10</appeared-in> | |
346 | |
347 <para> | |
348 Enables periodic health checks of the servers in a | |
349 <link id="upstream">group</link>. | |
350 </para> | |
351 | |
352 <para> | |
353 The following optional parameters are supported: | |
354 <list type="tag"> | |
355 | |
356 <tag-name id="interval"> | |
357 <literal>interval</literal>=<value>time</value> | |
358 </tag-name> | |
359 <tag-desc> | |
360 sets the interval between two consecutive health checks, | |
361 by default, 5 seconds; | |
362 </tag-desc> | |
363 | |
364 <tag-name id="fails"> | |
365 <literal>fails</literal>=<value>number</value> | |
366 </tag-name> | |
367 <tag-desc> | |
368 sets the number of consecutive failed health checks of a particular server | |
369 after which this server will be considered unhealthy, | |
370 by default, 1; | |
371 </tag-desc> | |
372 | |
373 <tag-name id="passes"> | |
374 <literal>passes</literal>=<value>number</value> | |
375 </tag-name> | |
376 <tag-desc> | |
377 sets the number of consecutive passed health checks of a particular server | |
378 after which the server will be considered healthy, | |
379 by default, 1; | |
380 </tag-desc> | |
381 | |
382 <tag-name id="hc_match"> | |
383 <literal>match</literal>=<value>name</value> | |
384 </tag-name> | |
385 <tag-desc> | |
386 specifies the <literal>match</literal> block configuring the tests that a | |
387 successful connection should pass in order for a health check to pass; | |
388 by default, only the ability to connect to the server is checked. | |
389 </tag-desc> | |
390 | |
391 </list> | |
392 </para> | |
393 | |
394 <para> | |
395 For example, | |
396 <example> | |
397 server { | |
398 proxy_pass backend; | |
399 health_check; | |
400 } | |
401 </example> | |
402 will check the ability to connect to each | |
403 server in the <literal>backend</literal> group every five seconds. | |
404 When a connection to the server cannot be established, | |
405 the health check will fail, and the server will | |
406 be considered unhealthy. | |
407 Client connections are not passed to unhealthy servers. | |
408 </para> | |
409 | |
410 <para> | |
411 Health checks can also be configured to test data obtained from the server. | |
412 Tests are configured separately using the <link id="match"/> directive | |
413 and referenced in the <literal>match</literal> parameter. | |
414 </para> | |
415 | |
416 <para> | |
417 The server group must reside in the <link id="zone">shared memory</link>. | |
418 </para> | |
419 | |
420 <para> | |
421 If several health checks are defined for the same group of servers, | |
422 a single failure of any check will make the corresponding server be | |
423 considered unhealthy. | |
424 </para> | |
425 | |
426 </directive> | |
427 | |
428 | |
429 <directive name="health_check_timeout"> | |
430 <syntax><value>timeout</value></syntax> | |
431 <default>5s</default> | |
432 <context>stream</context> | |
433 <context>server</context> | |
434 <appeared-in>1.7.10</appeared-in> | |
435 | |
436 <para> | |
437 Overrides the | |
438 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/> | |
439 value for health checks. | |
440 </para> | |
441 | |
442 </directive> | |
443 | |
444 | |
445 <directive name="match"> | |
446 <syntax block="yes"><value>name</value> </syntax> | |
447 <default/> | |
448 <context>stream</context> | |
449 <appeared-in>1.7.10</appeared-in> | |
450 | |
451 <para> | |
452 Defines the named test set used to verify server responses to health checks. | |
453 </para> | |
454 | |
455 <para> | |
456 The following parameters can be configured: | |
457 <list type="tag"> | |
458 | |
459 <tag-name> | |
460 <literal>send</literal> <value>string</value>; | |
461 </tag-name> | |
462 <tag-desc> | |
463 sends a <value>string</value> to the server; | |
464 </tag-desc> | |
465 | |
466 <tag-name> | |
467 <literal>expect</literal> <literal>~</literal> <value>regexp</value>; | |
468 </tag-name> | |
469 <tag-desc> | |
470 a regular expression that the data obtained from the server should match. | |
471 The regular expression is specified with the preceding | |
472 “<literal>~*</literal>” modifier (for case-insensitive matching), or the | |
473 “<literal>~</literal>” modifier (for case-sensitive matching). | |
474 </tag-desc> | |
475 | |
476 </list> | |
477 </para> | |
478 | |
479 <para> | |
480 Health check is passed if: | |
481 <list type="bullet"> | |
482 <listitem> | |
483 the connection was successfully established; | |
484 </listitem> | |
485 | |
486 <listitem> | |
487 the <value>string</value> from the <literal>send</literal> parameter, | |
488 if specified, was sent; | |
489 </listitem> | |
490 | |
491 <listitem> | |
492 the data obtained from the server matched the regular expression | |
493 from the <literal>expect</literal> parameter, if specified; | |
494 </listitem> | |
495 | |
496 <listitem> | |
497 the time elapsed does not exceed the value specified | |
498 in the <link id="health_check_timeout"/> directive. | |
499 </listitem> | |
500 | |
501 </list> | |
502 </para> | |
503 | |
504 <para> | |
505 Example: | |
506 <example> | |
507 upstream backend { | |
508 zone upstream_backend 10m; | |
509 server 127.0.0.1:12345; | |
510 } | |
511 | |
512 match http { | |
513 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n"; | |
514 expect ~ "200 OK"; | |
515 } | |
516 | |
517 server { | |
518 listen 12346; | |
519 proxy_pass backend; | |
520 health_check match=http; | |
521 } | |
522 </example> | |
523 </para> | |
524 | |
525 <para> | |
526 <note> | |
527 Only the first | |
528 <link doc="ngx_stream_proxy_module.xml" id="proxy_upstream_buffer"/> | |
529 bytes of data obtained from the server are examined. | |
530 </note> | |
531 </para> | |
532 | |
533 </directive> | |
534 | |
256 </section> | 535 </section> |
257 | 536 |
258 </module> | 537 </module> |