Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 956:488a3f738db0
Text revision of commercial modules.
author | Egor Nikitin <yegor.nikitin@gmail.com> |
---|---|
date | Fri, 02 Aug 2013 10:28:49 +0400 |
parents | 28d580f1eb63 |
children | 48ab154edf10 |
comparison
equal
deleted
inserted
replaced
955:28d580f1eb63 | 956:488a3f738db0 |
---|---|
445 | 445 |
446 <default/> | 446 <default/> |
447 <context>location</context> | 447 <context>location</context> |
448 | 448 |
449 <para> | 449 <para> |
450 Enables periodic health checks of servers in a | 450 Enables periodic health checks of the servers in a |
451 <link id="upstream">group</link> referenced in the surrounding location. | 451 <link id="upstream">group</link> referenced in the surrounding location. |
452 </para> | 452 </para> |
453 | 453 |
454 <para> | 454 <para> |
455 The following optional parameters are supported: | 455 The following optional parameters are supported: |
456 <list type="bullet"> | 456 <list type="bullet"> |
457 | 457 |
458 <listitem> | 458 <listitem> |
459 <literal>interval</literal> | 459 <literal>interval</literal> |
460 sets interval between two consecutive health checks, | 460 sets the interval between two consecutive health checks, |
461 defaults to five seconds; | 461 by default, 5 seconds; |
462 </listitem> | 462 </listitem> |
463 | 463 |
464 <listitem> | 464 <listitem> |
465 <literal>fails</literal> | 465 <literal>fails</literal> |
466 sets a number of consecutive failed health checks | 466 sets the number of consecutive failed health checks of a particular server |
467 after which the server will be considered unhealthy, | 467 after which this server will be considered unhealthy, |
468 defaults to 1; | 468 by default, 1; |
469 </listitem> | 469 </listitem> |
470 | 470 |
471 <listitem> | 471 <listitem> |
472 <literal>passes</literal> | 472 <literal>passes</literal> |
473 sets a number of consecutive passed health checks | 473 sets the number of consecutive passed health checks of a particular server |
474 after which the server will be considered healthy, | 474 after which the server will be considered healthy, |
475 defaults to 1; | 475 by default, 1; |
476 </listitem> | 476 </listitem> |
477 | 477 |
478 <listitem> | 478 <listitem> |
479 <literal>uri</literal> | 479 <literal>uri</literal> |
480 defines the URI used in health check requests, | 480 defines the URI used in health check requests, |
481 defaults to “<literal>/</literal>”; | 481 by default, “<literal>/</literal>”; |
482 </listitem> | 482 </listitem> |
483 | 483 |
484 <listitem> | 484 <listitem> |
485 <literal>match</literal> | 485 <literal>match</literal> |
486 names tests that a response should | 486 specifies the <literal>match</literal> block configuring the tests that a |
487 pass in order for a health check to pass, | 487 response should pass in order for a health check to pass; |
488 defaults to responses with status codes 2xx and 3xx. | 488 by default, the response should have status code 2xx or 3xx. |
489 </listitem> | 489 </listitem> |
490 | 490 |
491 </list> | 491 </list> |
492 </para> | 492 </para> |
493 | 493 |
498 proxy_pass http://backend; | 498 proxy_pass http://backend; |
499 health_check; | 499 health_check; |
500 } | 500 } |
501 </example> | 501 </example> |
502 will send “<literal>/</literal>” requests to each | 502 will send “<literal>/</literal>” requests to each |
503 server in the group <literal>backend</literal> every five seconds. | 503 server in the <literal>backend</literal> group every five seconds. |
504 If any communication errors or timeouts occur, or if a | 504 If any communication error or timeout occurs, or a |
505 proxied server responds with the status code other than | 505 proxied server responds with the status code other than |
506 2xx or 3xx, health check will fail, and the server will | 506 2xx or 3xx, the health check will fail, and the server will |
507 become unhealthy. | 507 be considered unhealthy. |
508 Client requests will not be passed to unhealthy servers. | 508 Client requests are not passed to unhealthy servers. |
509 </para> | 509 </para> |
510 | 510 |
511 <para> | 511 <para> |
512 Health checks can be configured to test status code of a response, | 512 Health checks can be configured to test the status code of a response, |
513 presence of certain header fields and their values, | 513 presence of certain header fields and their values, |
514 and/or the body contents. | 514 and the body contents. |
515 Tests are configured separately with the <link id="match"/> directives | 515 Tests are configured separately using the <link id="match"/> directive |
516 and referenced in the <literal>match</literal> parameter. | 516 and referenced in the <literal>match</literal> parameter. |
517 For example, | 517 For example: |
518 <example> | 518 <example> |
519 http { | 519 http { |
520 server { | 520 server { |
521 ... | 521 ... |
522 location / { | 522 location / { |
530 header Content-Type = text/html; | 530 header Content-Type = text/html; |
531 body ~ "Welcome to nginx!"; | 531 body ~ "Welcome to nginx!"; |
532 } | 532 } |
533 } | 533 } |
534 </example> | 534 </example> |
535 tells that for a health check to pass, a response should succeed, | 535 This configuration tells that for a health check to pass, the response to a |
536 health check request should succeed, | |
536 have status 200, content type “<literal>text/html</literal>”, | 537 have status 200, content type “<literal>text/html</literal>”, |
537 and contain “<literal>Welcome to nginx!</literal>” in the body. | 538 and contain “<literal>Welcome to nginx!</literal>” in the body. |
538 </para> | 539 </para> |
539 | 540 |
540 <para> | 541 <para> |
541 It is required that a group be in <link id="zone">shared memory</link>. | 542 The server group must reside in the <link id="zone">shared memory</link>. |
542 </para> | 543 </para> |
543 | 544 |
544 <para> | 545 <para> |
545 If several health checks are defined for the same group of servers, | 546 If several health checks are defined for the same group of servers, |
546 a single failure of any check will make the corresponding server | 547 a single failure of any check will make the corresponding server be |
547 to become unhealthy. | 548 considered unhealthy. |
548 </para> | 549 </para> |
549 | 550 |
550 <para> | 551 <para> |
551 <note> | 552 <note> |
552 This directive is available as part of our <commercial_version/> only. | 553 This directive is available as part of our <commercial_version/> only. |
564 <para> | 565 <para> |
565 Defines the named test set used to verify responses to health check requests. | 566 Defines the named test set used to verify responses to health check requests. |
566 </para> | 567 </para> |
567 | 568 |
568 <para> | 569 <para> |
569 The following can be tested in a response: | 570 The following items can be tested in a response: |
570 <list type="tag"> | 571 <list type="tag"> |
571 | 572 |
572 <tag-name><literal>status 200;</literal></tag-name> | 573 <tag-name><literal>status 200;</literal></tag-name> |
573 <tag-desc>status is 200</tag-desc> | 574 <tag-desc>status is 200</tag-desc> |
574 | 575 |
586 | 587 |
587 <tag-name><literal>status ! 400-599;</literal></tag-name> | 588 <tag-name><literal>status ! 400-599;</literal></tag-name> |
588 <tag-desc>status is not in the 400..599 range</tag-desc> | 589 <tag-desc>status is not in the 400..599 range</tag-desc> |
589 | 590 |
590 <tag-name><literal>status 301-303 307;</literal></tag-name> | 591 <tag-name><literal>status 301-303 307;</literal></tag-name> |
591 <tag-desc>status is one of 301, 302, 303, or 307</tag-desc> | 592 <tag-desc>status is either 301, 302, 303, or 307</tag-desc> |
592 | 593 |
593 </list> | 594 </list> |
594 | 595 |
595 <list type="tag"> | 596 <list type="tag"> |
596 | 597 |
641 </list> | 642 </list> |
642 </para> | 643 </para> |
643 | 644 |
644 <para> | 645 <para> |
645 If several tests are specified, | 646 If several tests are specified, |
646 the response matches only if it passes all tests. | 647 the response matches only if it matches all tests. |
647 <note> | 648 <note> |
648 Only the first 256k of body are examined. | 649 Only the first 256k of the response body are examined. |
649 </note> | 650 </note> |
650 </para> | 651 </para> |
651 | 652 |
652 <para> | 653 <para> |
653 Examples: | 654 Examples: |
695 | 696 |
696 <para> | 697 <para> |
697 Enables session affinity support. | 698 Enables session affinity support. |
698 The session is an object that is used to uniquely identify and maintain the | 699 The session is an object that is used to uniquely identify and maintain the |
699 state of a client during a given period of time. | 700 state of a client during a given period of time. |
700 If session affinity is enabled, a client’s requests are always passed to the | 701 If session affinity is enabled, requests from the same client are always passed |
701 same server (in a group of servers) once a session has been created. | 702 to the same server (in a group of servers) once a session has been created. |
702 Method used to create and track sessions must be specified by a separate | 703 The method that is used to create and track sessions must be specified in a |
703 directive, for example, <link id="sticky_cookie_insert"/>. | 704 separate directive, for example, <link id="sticky_cookie_insert"/>. |
704 <example> | 705 <example> |
705 upstream backend { | 706 upstream backend { |
706 server backend1.example.com; | 707 server backend1.example.com; |
707 server backend2.example.com; | 708 server backend2.example.com; |
708 | 709 |
719 The directive must be specified after the <link id="ip_hash"/> or the | 720 The directive must be specified after the <link id="ip_hash"/> or the |
720 <link id="least_conn"/> directives. | 721 <link id="least_conn"/> directives. |
721 </para> | 722 </para> |
722 | 723 |
723 <para> | 724 <para> |
724 Requests are processed as follows with the session affinity enabled: | 725 When the session affinity is enabled, a request is processed as follows: |
725 <list type="enum"> | 726 <list type="enum"> |
726 | 727 |
727 <listitem> | 728 <listitem> |
728 The lookup of session corresponding to request is performed. | 729 nginx looks up the session corresponding to the request. |
729 If the session is found, server identification data is extracted from it. | 730 If the session is found, the server identification data is extracted from it. |
730 This data is used by the server selection algorithm. | 731 This data is used by the server selection algorithm. |
731 </listitem> | 732 </listitem> |
732 | 733 |
733 <listitem> | 734 <listitem> |
734 The server to process the request is chosen according to the configured | 735 The server to process the request is chosen according to the configured |
735 balancing method, server information from session and the real state of | 736 balancing method, server information from the session, and the real state of |
736 servers in a group (up or down, failed, etc.). | 737 servers in a group (such as failed, up or down). |
737 </listitem> | 738 </listitem> |
738 | 739 |
739 <listitem> | 740 <listitem> |
740 The request is passed to the chosen server for processing. | 741 The request is passed to the chosen server for processing. |
741 If the chosen server does not match specified in the session | 742 If the chosen server is not the one specified in the session |
742 (due to being down, for example), the session is cleared | 743 (for example, because it is down), the session is cleared |
743 and the request is processed as it had no session. | 744 and the request is processed as if it had no session. |
744 </listitem> | 745 </listitem> |
745 | 746 |
746 <listitem> | 747 <listitem> |
747 The server returns the response. | 748 The server returns the response. |
748 </listitem> | 749 </listitem> |
749 | 750 |
750 <listitem> | 751 <listitem> |
751 If there was no session for the request, new session | 752 If there is no session for the request, a new session |
752 is created and server identification data is stored in it. | 753 is created and the server identification data is stored in it. |
753 </listitem> | 754 </listitem> |
754 | 755 |
755 </list> | 756 </list> |
756 </para> | 757 </para> |
757 | 758 |
771 [<literal>path=</literal><value>path</value>]</syntax> | 772 [<literal>path=</literal><value>path</value>]</syntax> |
772 <default/> | 773 <default/> |
773 <context>upstream</context> | 774 <context>upstream</context> |
774 | 775 |
775 <para> | 776 <para> |
776 Enables and configures the session tracking method, based on keeping | 777 Enables and configures the session tracking method that is based on keeping |
777 session information in HTTP cookies. | 778 session information in HTTP cookies. |
778 The directive must be specified after the <link id="ip_hash"/> or the | 779 The directive must be specified after the <link id="ip_hash"/> or the |
779 <link id="least_conn"/> directives. | 780 <link id="least_conn"/> directives. |
780 Example: | 781 Example: |
781 <example> | 782 <example> |
785 Additional parameters may be as follows: | 786 Additional parameters may be as follows: |
786 <list type="tag"> | 787 <list type="tag"> |
787 | 788 |
788 <tag-name><literal>expires</literal></tag-name> | 789 <tag-name><literal>expires</literal></tag-name> |
789 <tag-desc> | 790 <tag-desc> |
790 Sets a time during which a browser should keep the cookie. | 791 Sets the time for which a browser should keep the cookie. |
791 The parameter “<literal>max</literal>” sets the time to | 792 The parameter “<literal>max</literal>” sets the time to |
792 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | 793 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. |
793 This is the maximum time understood by old browsers. | 794 This is the maximum time understood by old browsers. |
794 </tag-desc> | 795 </tag-desc> |
795 | 796 |
796 <tag-name><literal>domain</literal></tag-name> | 797 <tag-name><literal>domain</literal></tag-name> |
797 <tag-desc> | 798 <tag-desc> |
798 Defines a domain for which the cookie is set. | 799 Defines the domain for which the cookie is set. |
799 </tag-desc> | 800 </tag-desc> |
800 | 801 |
801 <tag-name><literal>path</literal></tag-name> | 802 <tag-name><literal>path</literal></tag-name> |
802 <tag-desc> | 803 <tag-desc> |
803 Defines a path for which the cookie is set. | 804 Defines the path for which the cookie is set. |
804 </tag-desc> | 805 </tag-desc> |
805 | 806 |
806 </list> | 807 </list> |
807 If some parameter is omitted, then the corresponding cookie field is not set. | 808 If some parameter is omitted, the corresponding cookie field is not set. |
808 </para> | 809 </para> |
809 | 810 |
810 <para> | 811 <para> |
811 <note> | 812 <note> |
812 This directive is available as part of our <commercial_version/> only. | 813 This directive is available as part of our <commercial_version/> only. |
843 <syntax/> | 844 <syntax/> |
844 <default/> | 845 <default/> |
845 <context>location</context> | 846 <context>location</context> |
846 | 847 |
847 <para> | 848 <para> |
848 Turns on upstream configuration HTTP interface in a surrounding location. | 849 Turns on the HTTP interface of upstream configuration in the surrounding |
850 location. | |
849 Access to this location should be | 851 Access to this location should be |
850 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. | 852 <link doc="ngx_http_core_module.xml" id="satisfy">limited</link>. |
851 </para> | 853 </para> |
852 | 854 |
853 <para> | 855 <para> |
854 Configuration commands allow to: | 856 Configuration commands can be used to: |
855 <list type="bullet"> | 857 <list type="bullet"> |
856 | 858 |
857 <listitem>view all primary or backup servers in a group;</listitem> | 859 <listitem>view all primary or backup servers in a group;</listitem> |
858 | 860 |
859 <listitem>view an individual server;</listitem> | 861 <listitem>view an individual server;</listitem> |
860 | 862 |
861 <listitem>modify an individual server;</listitem> | 863 <listitem>modify an individual server;</listitem> |
862 | 864 |
863 <listitem>add a new server (see note below);</listitem> | 865 <listitem>add a new server (see the note below);</listitem> |
864 | 866 |
865 <listitem>remove an individual server.</listitem> | 867 <listitem>remove an individual server.</listitem> |
866 | 868 |
867 </list> | 869 </list> |
868 <note> | 870 <note> |
869 As noted in the <link id="server"/> directive, adding a server specified | 871 As noted in the <link id="server"/> directive, specifying a server |
870 as a domain name may result in several servers being added. | 872 as a domain name may result in several servers being added to the group. |
871 Since addresses in a group are not required to be unique, individual | 873 Since addresses in a group are not required to be unique, individual |
872 servers in a group can be uniquely referenced to only by their ID. | 874 servers in a group can be uniquely referenced to only by their ID. |
873 IDs are assigned automatically and shown when viewing group configuration. | 875 IDs are assigned automatically and shown on viewing of the group configuration. |
874 </note> | 876 </note> |
875 </para> | 877 </para> |
876 | 878 |
877 <para> | 879 <para> |
878 A command consists of parameters passed as request arguments, for example: | 880 A configuration command consists of parameters passed as request arguments, |
881 for example: | |
879 <example> | 882 <example> |
880 http://127.0.0.1/upstream_conf?upstream=appservers | 883 http://127.0.0.1/upstream_conf?upstream=appservers |
881 </example> | 884 </example> |
882 </para> | 885 </para> |
883 | 886 |
895 | 898 |
896 <tag-name> | 899 <tag-name> |
897 <literal>backup=</literal> | 900 <literal>backup=</literal> |
898 </tag-name> | 901 </tag-name> |
899 <tag-desc> | 902 <tag-desc> |
900 If unset, selects primary servers in the group. | 903 If not set, selects primary servers in the group. |
901 If set, selects backup servers in the group. | 904 If set, selects backup servers in the group. |
902 </tag-desc> | 905 </tag-desc> |
903 | 906 |
904 <tag-name> | 907 <tag-name> |
905 <literal>id=</literal><value>number</value></tag-name> | 908 <literal>id=</literal><value>number</value></tag-name> |
969 </tag-desc> | 972 </tag-desc> |
970 | 973 |
971 </list> | 974 </list> |
972 | 975 |
973 The first three parameters select a target the command applies to. | 976 The first three parameters select a target the command applies to. |
974 Without other parameters, configuration of the selected target | 977 Without other parameters, the command shows configuration of the selected |
975 is shown. | 978 target. |
976 </para> | 979 </para> |
977 | 980 |
978 <para> | 981 <para> |
979 For example, to view the primary servers in the group: | 982 For example, to view the primary servers in the group, send: |
980 <example> | 983 <example> |
981 http://127.0.0.1/upstream_conf?upstream=appservers | 984 http://127.0.0.1/upstream_conf?upstream=appservers |
982 </example> | 985 </example> |
983 | 986 |
984 To view the backup servers in the group: | 987 To view the backup servers in the group, send: |
985 <example> | 988 <example> |
986 http://127.0.0.1/upstream_conf?upstream=appservers&backup= | 989 http://127.0.0.1/upstream_conf?upstream=appservers&backup= |
987 </example> | 990 </example> |
988 | 991 |
989 To view an individual primary server in the group: | 992 To view an individual primary server in the group, send: |
990 <example> | 993 <example> |
991 http://127.0.0.1/upstream_conf?upstream=appservers&id=42 | 994 http://127.0.0.1/upstream_conf?upstream=appservers&id=42 |
992 </example> | 995 </example> |
993 | 996 |
994 To view an individual backup server in the group: | 997 To view an individual backup server in the group, send: |
995 <example> | 998 <example> |
996 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42 | 999 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42 |
997 </example> | 1000 </example> |
998 </para> | 1001 </para> |
999 | 1002 |
1000 <para> | 1003 <para> |
1001 To add a new primary or backup server to the group, | 1004 To add a new primary or backup server to the group, |
1002 its address should be specified in the “<literal>server=</literal>” parameter. | 1005 specify its address in the “<literal>server=</literal>” parameter. |
1003 Without other parameters specified, a server will be added with other | 1006 Without other parameters specified, a server will be added with other |
1004 parameters set to their default values (see the <link id="server"/> directive). | 1007 parameters set to their default values (see the <link id="server"/> directive). |
1005 </para> | 1008 </para> |
1006 | 1009 |
1007 <para> | 1010 <para> |
1008 For example, to add a new primary server to the group: | 1011 For example, to add a new primary server to the group, send: |
1009 <example> | 1012 <example> |
1010 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080 | 1013 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080 |
1011 </example> | 1014 </example> |
1012 | 1015 |
1013 To add a new backup server to the group: | 1016 To add a new backup server to the group, send: |
1014 <example> | 1017 <example> |
1015 http://127.0.0.1/upstream_conf?add=&upstream=appservers&backup=&server=127.0.0.1:8080 | 1018 http://127.0.0.1/upstream_conf?add=&upstream=appservers&backup=&server=127.0.0.1:8080 |
1016 </example> | 1019 </example> |
1017 | 1020 |
1018 To add a new primary server to the group, | 1021 To add a new primary server to the group, |
1019 set its parameters to non-default values | 1022 set its parameters to non-default values |
1020 and mark it “<literal>down</literal>”: | 1023 and mark it as “<literal>down</literal>” by sending: |
1021 <example> | 1024 <example> |
1022 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down= | 1025 http://127.0.0.1/upstream_conf?add=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down= |
1023 </example> | 1026 </example> |
1024 </para> | 1027 </para> |
1025 | 1028 |
1026 <para> | 1029 <para> |
1027 To remove an individual primary or backup server from the group, | 1030 To remove an individual primary or backup server from the group, |
1028 it should be selected with the <literal>id=</literal> parameter. | 1031 select it with the <literal>id=</literal> parameter. |
1029 </para> | 1032 </para> |
1030 | 1033 |
1031 <para> | 1034 <para> |
1032 For example, to remove an individual primary server from the group: | 1035 For example, to remove an individual primary server from the group, send: |
1033 <example> | 1036 <example> |
1034 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42 | 1037 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&id=42 |
1035 </example> | 1038 </example> |
1036 | 1039 |
1037 To remove an individual backup server from the group: | 1040 To remove an individual backup server from the group, send: |
1038 <example> | 1041 <example> |
1039 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42 | 1042 http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42 |
1040 </example> | 1043 </example> |
1041 </para> | 1044 </para> |
1042 | 1045 |
1043 <para> | 1046 <para> |
1044 To modify an individual primary or backup server in the group, | 1047 To modify an individual primary or backup server in the group, |
1045 it should be selected with the <literal>id=</literal> parameter. | 1048 select it with the <literal>id=</literal> parameter. |
1046 </para> | 1049 </para> |
1047 | 1050 |
1048 <para> | 1051 <para> |
1049 For example, to modify an individual primary server in the group | 1052 For example, to modify an individual primary server in the group |
1050 by marking it “<literal>down</literal>”: | 1053 by marking it as “<literal>down</literal>”, send: |
1051 <example> | 1054 <example> |
1052 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&down= | 1055 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&down= |
1053 </example> | 1056 </example> |
1054 | 1057 |
1055 To modify address of an individual backup server in the group: | 1058 To modify the address of an individual backup server in the group, send: |
1056 <example> | 1059 <example> |
1057 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42&server=192.0.2.3:8123 | 1060 http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42&server=192.0.2.3:8123 |
1058 </example> | 1061 </example> |
1059 | 1062 |
1060 To modify other parameters of an individual primary server in the group: | 1063 To modify other parameters of an individual primary server in the group, send: |
1061 <example> | 1064 <example> |
1062 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4 | 1065 http://127.0.0.1/upstream_conf?upstream=appservers&id=42&max_fails=3&weight=4 |
1063 </example> | 1066 </example> |
1064 | 1067 |
1065 </para> | 1068 </para> |