Mercurial > hg > nginx-site

comparison xml/en/docs/stream/ngx_stream_upstream_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 a58b35cc0823
children eb58ee50561d
comparison
equal deleted inserted replaced
1946:37df1535ea91 1947:6b6d0e844bf7
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="24"> 12 rev="25">
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)
44 } 44 }
45 </example> 45 </example>
46 </para> 46 </para>
47 47
48 <para> 48 <para>
49 Dynamically configurable group, 49 Dynamically configurable group with
50 periodic <link doc="ngx_stream_upstream_hc_module.xml">health checks</link> is
50 available as part of our 51 available as part of our
51 <commercial_version>commercial subscription</commercial_version>: 52 <commercial_version>commercial subscription</commercial_version>:
52 <example> 53 <example>
53 resolver 10.0.0.1; 54 resolver 10.0.0.1;
54 55
295 <literal>slow_start</literal>=<value>time</value> 296 <literal>slow_start</literal>=<value>time</value>
296 </tag-name> 297 </tag-name>
297 <tag-desc> 298 <tag-desc>
298 sets the <value>time</value> during which the server will recover its weight 299 sets the <value>time</value> during which the server will recover its weight
299 from zero to a nominal value, when unhealthy server becomes 300 from zero to a nominal value, when unhealthy server becomes
300 <link id="health_check">healthy</link>, 301 <link doc="ngx_stream_upstream_hc_module.xml" id="health_check">healthy</link>,
301 or when the server becomes available after a period of time 302 or when the server becomes available after a period of time
302 it was considered <link id="fail_timeout">unavailable</link>. 303 it was considered <link id="fail_timeout">unavailable</link>.
303 Default value is zero, i.e. slow start is disabled. 304 Default value is zero, i.e. slow start is disabled.
304 <note> 305 <note>
305 The parameter cannot be used along with the 306 The parameter cannot be used along with the
489 </note> 490 </note>
490 </para> 491 </para>
491 492
492 </directive> 493 </directive>
493 494
494
495 <directive name="health_check">
496 <syntax>[<value>parameters</value>]</syntax>
497 <default/>
498 <context>server</context>
499
500 <para>
501 Enables periodic health checks of the servers in a
502 <link id="upstream">group</link>.
503 </para>
504
505 <para>
506 The following optional parameters are supported:
507 <list type="tag">
508
509 <tag-name id="interval">
510 <literal>interval</literal>=<value>time</value>
511 </tag-name>
512 <tag-desc>
513 sets the interval between two consecutive health checks,
514 by default, 5 seconds.
515 </tag-desc>
516
517 <tag-name id="health_check_jitter">
518 <literal>jitter</literal>=<value>time</value>
519 </tag-name>
520 <tag-desc>
521 sets the time within which
522 each health check will be randomly delayed,
523 by default, there is no delay.
524 </tag-desc>
525
526 <tag-name id="fails">
527 <literal>fails</literal>=<value>number</value>
528 </tag-name>
529 <tag-desc>
530 sets the number of consecutive failed health checks of a particular server
531 after which this server will be considered unhealthy,
532 by default, 1.
533 </tag-desc>
534
535 <tag-name id="passes">
536 <literal>passes</literal>=<value>number</value>
537 </tag-name>
538 <tag-desc>
539 sets the number of consecutive passed health checks of a particular server
540 after which the server will be considered healthy,
541 by default, 1.
542 </tag-desc>
543
544 <tag-name id="health_check_mandatory">
545 <literal>mandatory</literal>
546 </tag-name>
547 <tag-desc>
548 sets the initial “checking” state for a server
549 until the first health check is completed (1.11.7).
550 If the parameter is not specified,
551 the server will be initially considered healthy.
552 </tag-desc>
553
554 <tag-name id="hc_match">
555 <literal>match</literal>=<value>name</value>
556 </tag-name>
557 <tag-desc>
558 specifies the <literal>match</literal> block configuring the tests that a
559 successful connection should pass in order for a health check to pass.
560 By default, for TCP, only the ability
561 to establish a TCP connection with the server is checked.
562 For <link id="health_check_udp">UDP</link>, the absence of
563 ICMP “<literal>Destination Unreachable</literal>” message is expected
564 in reply to the sent string “<literal>nginx health check</literal>”.
565 <note>
566 Prior to version 1.11.7, by default, UDP health check
567 required a <link id="hc_match">match</link> block with the
568 <link id="match_send">send</link> and <link id="match_expect">expect</link>
569 parameters.
570 </note>
571 </tag-desc>
572
573 <tag-name id="health_check_port">
574 <literal>port</literal>=<value>number</value>
575 </tag-name>
576 <tag-desc>
577 defines the port used when connecting to a server
578 to perform a health check (1.9.7).
579 By default, equals the <link id="server"/> port.
580 </tag-desc>
581
582 <tag-name id="health_check_udp">
583 <literal>udp</literal>
584 </tag-name>
585 <tag-desc>
586 specifies that the <literal>UDP</literal> protocol should be used for
587 health checks instead of the default <literal>TCP</literal> protocol (1.9.13).
588 </tag-desc>
589
590 </list>
591 </para>
592
593 <para>
594 For example,
595 <example>
596 server {
597 proxy_pass backend;
598 health_check;
599 }
600 </example>
601 will check the ability to establish a TCP connection to each server
602 in the <literal>backend</literal> group every five seconds.
603 When a connection to the server cannot be established,
604 the health check will fail, and the server will
605 be considered unhealthy.
606 Client connections are not passed to unhealthy servers
607 and servers in the “checking” state.
608 </para>
609
610 <para>
611 Health checks can also be configured to test data obtained from the server.
612 Tests are configured separately using the <link id="match"/> directive
613 and referenced in the <literal>match</literal> parameter.
614 </para>
615
616 <para>
617 The server group must reside in the <link id="zone">shared memory</link>.
618 </para>
619
620 <para>
621 If several health checks are defined for the same group of servers,
622 a single failure of any check will make the corresponding server be
623 considered unhealthy.
624 </para>
625
626 <para>
627 <note>
628 This directive is available as part of our
629 <commercial_version>commercial subscription</commercial_version>.
630 </note>
631 </para>
632
633 </directive>
634
635
636 <directive name="health_check_timeout">
637 <syntax><value>timeout</value></syntax>
638 <default>5s</default>
639 <context>stream</context>
640 <context>server</context>
641
642 <para>
643 Overrides the
644 <link doc="ngx_stream_proxy_module.xml" id="proxy_timeout"/>
645 value for health checks.
646 </para>
647
648 <para>
649 <note>
650 This directive is available as part of our
651 <commercial_version>commercial subscription</commercial_version>.
652 </note>
653 </para>
654
655 </directive>
656
657
658 <directive name="match">
659 <syntax block="yes"><value>name</value> </syntax>
660 <default/>
661 <context>stream</context>
662
663 <para>
664 Defines the named test set used to verify server responses to health checks.
665 </para>
666
667 <para>
668 The following parameters can be configured:
669 <list type="tag">
670
671 <tag-name id="match_send">
672 <literal>send</literal> <value>string</value>;
673 </tag-name>
674 <tag-desc>
675 sends a <value>string</value> to the server;
676 </tag-desc>
677
678 <tag-name id="match_expect">
679 <literal>expect</literal> <value>string</value> |
680 <literal>~</literal> <value>regex</value>;
681 </tag-name>
682 <tag-desc>
683 a literal string (1.9.12) or a regular expression
684 that the data obtained from the server should match.
685 The regular expression is specified with the preceding
686 “<literal>~*</literal>” modifier (for case-insensitive matching), or the
687 “<literal>~</literal>” modifier (for case-sensitive matching).
688 </tag-desc>
689
690 </list>
691 Both <literal>send</literal> and <literal>expect</literal> parameters
692 can contain hexadecimal literals with the prefix “<literal>\x</literal>”
693 followed by two hex digits, for example, “<literal>\x80</literal>” (1.9.12).
694 </para>
695
696 <para>
697 Health check is passed if:
698 <list type="bullet">
699 <listitem>
700 the TCP connection was successfully established;
701 </listitem>
702
703 <listitem>
704 the <value>string</value> from the <literal>send</literal> parameter,
705 if specified, was sent;
706 </listitem>
707
708 <listitem>
709 the data obtained from the server matched the string or regular expression
710 from the <literal>expect</literal> parameter, if specified;
711 </listitem>
712
713 <listitem>
714 the time elapsed does not exceed the value specified
715 in the <link id="health_check_timeout"/> directive.
716 </listitem>
717
718 </list>
719 </para>
720
721 <para>
722 Example:
723 <example>
724 upstream backend {
725 zone upstream_backend 10m;
726 server 127.0.0.1:12345;
727 }
728
729 match http {
730 send "GET / HTTP/1.0\r\nHost: localhost\r\n\r\n";
731 expect ~ "200 OK";
732 }
733
734 server {
735 listen 12346;
736 proxy_pass backend;
737 health_check match=http;
738 }
739 </example>
740 </para>
741
742 <para>
743 <note>
744 Only the first
745 <link doc="ngx_stream_proxy_module.xml" id="proxy_buffer_size"/>
746 bytes of data obtained from the server are examined.
747 </note>
748 </para>
749
750 <para>
751 <note>
752 This directive is available as part of our
753 <commercial_version>commercial subscription</commercial_version>.
754 </note>
755 </para>
756
757 </directive>
758
759 </section> 495 </section>
760 496
761 497
762 <section id="variables" name="Embedded Variables"> 498 <section id="variables" name="Embedded Variables">
763 499