Mercurial > hg > nginx-site
comparison xml/en/docs/stream/ngx_stream_upstream_module.xml @ 1680:57c3f36b3b6a
Updated docs for the upcoming NGINX Plus release.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Sun, 10 Apr 2016 00:12:49 +0300 |
parents | f5dcf57c5eb5 |
children | 1dbef8ab47c7 |
comparison
equal
deleted
inserted
replaced
1679:e9ad1cae4401 | 1680:57c3f36b3b6a |
---|---|
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="10"> | 12 rev="11"> |
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.9.0) | 17 The <literal>ngx_stream_upstream_module</literal> module (1.9.0) |
57 | 57 |
58 server backend1.example.com:12345 weight=5; | 58 server backend1.example.com:12345 weight=5; |
59 server backend2.example.com:12345 fail_timeout=5s slow_start=30s; | 59 server backend2.example.com:12345 fail_timeout=5s slow_start=30s; |
60 server 192.0.2.1:12345 max_fails=3; | 60 server 192.0.2.1:12345 max_fails=3; |
61 server backend3.example.com:12345 resolve; | 61 server backend3.example.com:12345 resolve; |
62 server backend4.example.com service=http resolve; | |
62 | 63 |
63 server backup1.example.com:12345 backup; | 64 server backup1.example.com:12345 backup; |
64 server backup2.example.com:12345 backup; | 65 server backup2.example.com:12345 backup; |
65 } | 66 } |
66 | 67 |
236 ... | 237 ... |
237 server example.com:12345 resolve; | 238 server example.com:12345 resolve; |
238 } | 239 } |
239 } | 240 } |
240 </example> | 241 </example> |
242 </para> | |
243 </tag-desc> | |
244 | |
245 <tag-name id="service"> | |
246 <literal>service</literal>=<value>name</value> | <value>_name._protocol</value> | |
247 </tag-name> | |
248 <tag-desc> | |
249 enables resolving of DNS | |
250 <link url="https://tools.ietf.org/html/rfc2782">SRV</link> | |
251 records and sets the service <value>name</value>, | |
252 or <value>name</value> and <value>protocol</value> in the following format: | |
253 <value>_name._protocol</value> (1.9.13). | |
254 If only the <value>name</value> is specified, | |
255 the <literal>TCP</literal> protocol is used. | |
256 <para> | |
257 In order for this parameter to work, it is necessary to specify | |
258 the <link id="resolve"/> parameter for the server | |
259 and specify a hostname without a port number: | |
260 <example> | |
261 server backend.example.com service=http resolve; | |
262 server backend.example.com service=_http._tcp resolve; | |
263 </example> | |
264 Both directives specify the same SRV record: | |
265 <literal>_http._tcp.backend.example.com</literal>. | |
266 </para> | |
267 | |
268 <para> | |
269 Highest-priority SRV records | |
270 (records with the same lowest-number priority value) | |
271 are resolved as primary servers, | |
272 the rest of SRV records are resolved as backup servers. | |
273 If the <link id="backup"/> parameter is specified for the server, | |
274 high-priority SRV records are resolved as backup servers, | |
275 the rest of SRV records are ignored. | |
241 </para> | 276 </para> |
242 </tag-desc> | 277 </tag-desc> |
243 | 278 |
244 <tag-name id="slow_start"> | 279 <tag-name id="slow_start"> |
245 <literal>slow_start</literal>=<value>time</value> | 280 <literal>slow_start</literal>=<value>time</value> |
457 <tag-name id="hc_match"> | 492 <tag-name id="hc_match"> |
458 <literal>match</literal>=<value>name</value> | 493 <literal>match</literal>=<value>name</value> |
459 </tag-name> | 494 </tag-name> |
460 <tag-desc> | 495 <tag-desc> |
461 specifies the <literal>match</literal> block configuring the tests that a | 496 specifies the <literal>match</literal> block configuring the tests that a |
462 successful connection should pass in order for a health check to pass; | 497 successful connection should pass in order for a health check to pass. |
463 by default, only the ability to connect to the server is checked; | 498 By default, |
499 only the ability to establish a TCP connection with the server is checked; | |
464 </tag-desc> | 500 </tag-desc> |
465 | 501 |
466 <tag-name id="health_check_port"> | 502 <tag-name id="health_check_port"> |
467 <literal>port</literal>=<value>number</value> | 503 <literal>port</literal>=<value>number</value> |
468 </tag-name> | 504 </tag-name> |
469 <tag-desc> | 505 <tag-desc> |
470 defines the port used when connecting to a server | 506 defines the port used when connecting to a server |
471 to perform a health check (1.9.7); | 507 to perform a health check (1.9.7); |
472 by default, equals the <link id="server"/> port. | 508 by default, equals the <link id="server"/> port; |
509 </tag-desc> | |
510 | |
511 <tag-name id="health_check_udp"> | |
512 <literal>udp</literal> | |
513 </tag-name> | |
514 <tag-desc> | |
515 specifies that the <literal>UDP</literal> protocol should be used for | |
516 health checks instead of the default <literal>TCP</literal> protocol (1.9.13); | |
517 requires a <link id="hc_match">match</link> block with the | |
518 <link id="match_send">send</link> and <link id="match_expect">expect</link> | |
519 parameters. | |
473 </tag-desc> | 520 </tag-desc> |
474 | 521 |
475 </list> | 522 </list> |
476 </para> | 523 </para> |
477 | 524 |
481 server { | 528 server { |
482 proxy_pass backend; | 529 proxy_pass backend; |
483 health_check; | 530 health_check; |
484 } | 531 } |
485 </example> | 532 </example> |
486 will check the ability to connect to each | 533 will check the ability to establish a TCP connection to each server |
487 server in the <literal>backend</literal> group every five seconds. | 534 in the <literal>backend</literal> group every five seconds. |
488 When a connection to the server cannot be established, | 535 When a connection to the server cannot be established, |
489 the health check will fail, and the server will | 536 the health check will fail, and the server will |
490 be considered unhealthy. | 537 be considered unhealthy. |
491 Client connections are not passed to unhealthy servers. | 538 Client connections are not passed to unhealthy servers. |
492 </para> | 539 </para> |
550 | 597 |
551 <para> | 598 <para> |
552 The following parameters can be configured: | 599 The following parameters can be configured: |
553 <list type="tag"> | 600 <list type="tag"> |
554 | 601 |
555 <tag-name> | 602 <tag-name id="match_send"> |
556 <literal>send</literal> <value>string</value>; | 603 <literal>send</literal> <value>string</value>; |
557 </tag-name> | 604 </tag-name> |
558 <tag-desc> | 605 <tag-desc> |
559 sends a <value>string</value> to the server; | 606 sends a <value>string</value> to the server; |
560 </tag-desc> | 607 </tag-desc> |
561 | 608 |
562 <tag-name> | 609 <tag-name id="match_expect"> |
563 <literal>expect</literal> <literal>~</literal> <value>regexp</value>; | 610 <literal>expect</literal> <value>string</value> | |
564 </tag-name> | 611 <literal>~</literal> <value>regex</value>; |
565 <tag-desc> | 612 </tag-name> |
566 a regular expression that the data obtained from the server should match. | 613 <tag-desc> |
614 a literal string (1.9.12) or a regular expression | |
615 that the data obtained from the server should match. | |
567 The regular expression is specified with the preceding | 616 The regular expression is specified with the preceding |
568 “<literal>~*</literal>” modifier (for case-insensitive matching), or the | 617 “<literal>~*</literal>” modifier (for case-insensitive matching), or the |
569 “<literal>~</literal>” modifier (for case-sensitive matching). | 618 “<literal>~</literal>” modifier (for case-sensitive matching). |
570 </tag-desc> | 619 </tag-desc> |
571 | 620 |
572 </list> | 621 </list> |
622 Both <literal>send</literal> and <literal>expect</literal> parameters | |
623 can contain hexadecimal literals with the prefix “<literal>\x</literal>” | |
624 followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12). | |
573 </para> | 625 </para> |
574 | 626 |
575 <para> | 627 <para> |
576 Health check is passed if: | 628 Health check is passed if: |
577 <list type="bullet"> | 629 <list type="bullet"> |
578 <listitem> | 630 <listitem> |
579 the connection was successfully established; | 631 the TCP connection was successfully established; |
580 </listitem> | 632 </listitem> |
581 | 633 |
582 <listitem> | 634 <listitem> |
583 the <value>string</value> from the <literal>send</literal> parameter, | 635 the <value>string</value> from the <literal>send</literal> parameter, |
584 if specified, was sent; | 636 if specified, was sent; |
585 </listitem> | 637 </listitem> |
586 | 638 |
587 <listitem> | 639 <listitem> |
588 the data obtained from the server matched the regular expression | 640 the data obtained from the server matched the string or regular expression |
589 from the <literal>expect</literal> parameter, if specified; | 641 from the <literal>expect</literal> parameter, if specified; |
590 </listitem> | 642 </listitem> |
591 | 643 |
592 <listitem> | 644 <listitem> |
593 the time elapsed does not exceed the value specified | 645 the time elapsed does not exceed the value specified |