Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1026:3056640d5022
Upstream: documented new "sticky" features.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 23 Oct 2013 15:19:38 +0400 |
parents | 2ad2f30efdf2 |
children | 6c021feec587 |
comparison
equal
deleted
inserted
replaced
1025:36cf06691ff1 | 1026:3056640d5022 |
---|---|
8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> | 8 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> |
9 | 9 |
10 <module name="Module ngx_http_upstream_module" | 10 <module name="Module ngx_http_upstream_module" |
11 link="/en/docs/http/ngx_http_upstream_module.html" | 11 link="/en/docs/http/ngx_http_upstream_module.html" |
12 lang="en" | 12 lang="en" |
13 rev="11"> | 13 rev="12"> |
14 | 14 |
15 <section id="summary"> | 15 <section id="summary"> |
16 | 16 |
17 <para> | 17 <para> |
18 The <literal>ngx_http_upstream_module</literal> module | 18 The <literal>ngx_http_upstream_module</literal> module |
201 <tag-desc> | 201 <tag-desc> |
202 marks the server as permanently unavailable; used along with | 202 marks the server as permanently unavailable; used along with |
203 the <link id="ip_hash"/> directive. | 203 the <link id="ip_hash"/> directive. |
204 </tag-desc> | 204 </tag-desc> |
205 | 205 |
206 <tag-name><literal>route</literal>=<value>string</value></tag-name> | |
207 <tag-desc> | |
208 sets the server route name. | |
209 <note> | |
210 This functionality is available as part of our <commercial_version/> only. | |
211 </note> | |
212 </tag-desc> | |
213 | |
206 </list> | 214 </list> |
207 </para> | 215 </para> |
208 | 216 |
209 <para> | 217 <para> |
210 Example: | 218 Example: |
691 </para> | 699 </para> |
692 | 700 |
693 </directive> | 701 </directive> |
694 | 702 |
695 | 703 |
696 <directive name="sticky_cookie_insert"> | 704 <directive name="sticky"> |
697 <syntax><value>name</value> | 705 <syntax><literal>cookie</literal> <value>name</value> |
698 [<literal>expires=</literal><value>time</value>] | 706 [<literal>expires=</literal><value>time</value>] |
699 [<literal>domain=</literal><value>host</value>] | 707 [<literal>domain=</literal><value>domain</value>] |
700 [<literal>path=</literal><value>path</value>]</syntax> | 708 [<literal>path=</literal><value>path</value>]</syntax> |
709 <syntax><literal>route</literal> <value>variable</value> ...</syntax> | |
701 <default/> | 710 <default/> |
702 <context>upstream</context> | 711 <context>upstream</context> |
712 <appeared-in>1.5.7</appeared-in> | |
703 | 713 |
704 <para> | 714 <para> |
705 Enables session affinity, which causes requests from the same client to be | 715 Enables session affinity, which causes requests from the same client to be |
706 passed to the same server in a group of servers. | 716 passed to the same server in a group of servers. |
707 Example: | 717 Two methods are available, |
718 <literal>cookie</literal> and <literal>route</literal>. | |
719 </para> | |
720 | |
721 <para> | |
722 When the <literal>cookie</literal> method is used, information about the | |
723 designated server is passed in an HTTP cookie: | |
708 <example> | 724 <example> |
709 upstream backend { | 725 upstream backend { |
710 server backend1.example.com; | 726 server backend1.example.com; |
711 server backend2.example.com; | 727 server backend2.example.com; |
712 | 728 |
713 sticky_cookie_insert srv_id expires=1h domain=example.com path=/; | 729 sticky cookie srv_id expires=1h domain=.example.com path=/; |
714 } | 730 } |
715 </example> | 731 </example> |
716 </para> | 732 </para> |
717 | 733 |
718 <para> | 734 <para> |
719 A request that comes from a client not yet bound to a particular server | 735 A request that comes from a client not yet bound to a particular server |
720 is passed to the server selected by the configured balancing method. | 736 is passed to the server selected by the configured balancing method. |
721 Further requests from the same client are passed to the same server. | 737 Further requests from the same client are passed to the same server. |
722 If a request cannot be processed by the bound server, the new server | 738 If the designated server cannot process a request, the new server is |
723 is selected as if the client was not yet bound. | 739 selected as if the client has not been bound yet. |
724 </para> | 740 </para> |
725 | 741 |
726 <para> | 742 <para> |
727 Information about the bound server is kept in an HTTP cookie. | 743 The first parameter sets the name of the cookie to be set or inspected. |
728 The first parameter sets the name of the cookie to be inserted or inspected. | |
729 Additional parameters may be as follows: | 744 Additional parameters may be as follows: |
730 <list type="tag"> | 745 <list type="tag"> |
731 | 746 |
732 <tag-name><literal>expires</literal></tag-name> | 747 <tag-name><literal>expires</literal></tag-name> |
733 <tag-desc> | 748 <tag-desc> |
734 Sets the time for which a browser should keep the cookie. | 749 Sets the time for which a browser should keep the cookie. |
735 The parameter <literal>max</literal> will cause the cookie to expire on | 750 The special value <literal>max</literal> will cause the cookie to expire on |
736 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | 751 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. |
737 This is the maximum time understood by old browsers. | 752 This is the maximum time understood by old browsers. |
738 If the parameter is not specified, it will cause the cookie to expire at | 753 If the parameter is not specified, it will cause the cookie to expire at |
739 the end of a browser session. | 754 the end of a browser session. |
740 </tag-desc> | 755 </tag-desc> |
752 </list> | 767 </list> |
753 If any parameters are omitted, the corresponding cookie fields are not set. | 768 If any parameters are omitted, the corresponding cookie fields are not set. |
754 </para> | 769 </para> |
755 | 770 |
756 <para> | 771 <para> |
772 When the <literal>route</literal> method is used, proxied server assigns | |
773 client a route on receipt of the first request. | |
774 All subsequent requests from this client will carry routing information | |
775 in a cookie or URI. | |
776 This information is compared with the “<literal>route</literal>” parameter | |
777 of the <link id="server"/> directive to identify the server to which the | |
778 request should be proxied. | |
779 If the designated server cannot process a request, the new server is | |
780 selected by the configured balancing method as if there is no routing | |
781 information in the request. | |
782 </para> | |
783 | |
784 <para> | |
785 The parameters of the <literal>route</literal> method specify variables that | |
786 may contain routing information. | |
787 The first non-empty variable is used to find the matching server. | |
788 </para> | |
789 | |
790 <para> | |
791 Example: | |
792 <example> | |
793 map $cookie_jsessionid $route_cookie { | |
794 ~.+\.(?P<route>\w+)$ $route; | |
795 } | |
796 | |
797 map $request_uri $route_uri { | |
798 ~jsessionid=.+\.(?P<route>\w+)$ $route; | |
799 } | |
800 | |
801 upstream backend { | |
802 server backend1.example.com route=a; | |
803 server backend2.example.com route=b; | |
804 | |
805 sticky route $route_cookie $route_uri; | |
806 } | |
807 </example> | |
808 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie | |
809 if present in a request. | |
810 Otherwise, the route from the URI is used. | |
811 </para> | |
812 | |
813 <para> | |
757 <note> | 814 <note> |
758 This directive is available as part of our <commercial_version/> only. | 815 This directive is available as part of our <commercial_version/> only. |
816 </note> | |
817 </para> | |
818 | |
819 </directive> | |
820 | |
821 | |
822 <directive name="sticky_cookie_insert"> | |
823 <syntax><value>name</value> | |
824 [<literal>expires=</literal><value>time</value>] | |
825 [<literal>domain=</literal><value>domain</value>] | |
826 [<literal>path=</literal><value>path</value>]</syntax> | |
827 <default/> | |
828 <context>upstream</context> | |
829 | |
830 <para> | |
831 This directive is obsolete since version 1.5.7. | |
832 An equivalent | |
833 <link id="sticky"/> directive with a new syntax should be used instead: | |
834 <note> | |
835 <literal>sticky cookie</literal> <value>name</value> | |
836 [<literal>expires=</literal><value>time</value>] | |
837 [<literal>domain=</literal><value>domain</value>] | |
838 [<literal>path=</literal><value>path</value>]; | |
759 </note> | 839 </note> |
760 </para> | 840 </para> |
761 | 841 |
762 </directive> | 842 </directive> |
763 | 843 |
888 | 968 |
889 <tag-name> | 969 <tag-name> |
890 <literal>up=</literal></tag-name> | 970 <literal>up=</literal></tag-name> |
891 <tag-desc> | 971 <tag-desc> |
892 The opposite of the “<literal>down</literal>” parameter | 972 The opposite of the “<literal>down</literal>” parameter |
973 of the <link id="server"/> directive. | |
974 </tag-desc> | |
975 | |
976 <tag-name> | |
977 <literal>route=</literal><value>string</value></tag-name> | |
978 <tag-desc> | |
979 Same as the “<literal>route</literal>” parameter | |
893 of the <link id="server"/> directive. | 980 of the <link id="server"/> directive. |
894 </tag-desc> | 981 </tag-desc> |
895 | 982 |
896 </list> | 983 </list> |
897 | 984 |