Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1003:271e735e4576
Undocumented unreleased changes to the sticky module.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 17 Oct 2013 13:54:54 +0400 |
parents | 35ae9ded0465 |
children | 2ad2f30efdf2 |
comparison
equal
deleted
inserted
replaced
1002:c163e997d819 | 1003:271e735e4576 |
---|---|
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="12"> | 13 rev="10"> |
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 | |
214 </list> | 206 </list> |
215 </para> | 207 </para> |
216 | 208 |
217 <para> | 209 <para> |
218 Example: | 210 Example: |
699 </para> | 691 </para> |
700 | 692 |
701 </directive> | 693 </directive> |
702 | 694 |
703 | 695 |
704 <directive name="sticky"> | 696 <directive name="sticky_cookie_insert"> |
705 <syntax><literal>cookie</literal> <value>name</value> | 697 <syntax><value>name</value> |
706 [<literal>expires=</literal><value>time</value>] | 698 [<literal>expires=</literal><value>time</value>] |
707 [<literal>domain=</literal><value>domain</value>] | 699 [<literal>domain=</literal><value>host</value>] |
708 [<literal>path=</literal><value>path</value>]</syntax> | 700 [<literal>path=</literal><value>path</value>]</syntax> |
709 <syntax><literal>route</literal> <value>variable</value> ...</syntax> | |
710 <default/> | 701 <default/> |
711 <context>upstream</context> | 702 <context>upstream</context> |
712 <appeared-in>1.5.7</appeared-in> | |
713 | 703 |
714 <para> | 704 <para> |
715 Enables session affinity, which causes requests from the same client to be | 705 Enables session affinity, which causes requests from the same client to be |
716 passed to the same server in a group of servers. | 706 passed to the same server in a group of servers. |
717 Two methods are available, | 707 Example: |
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: | |
724 <example> | 708 <example> |
725 upstream backend { | 709 upstream backend { |
726 server backend1.example.com; | 710 server backend1.example.com; |
727 server backend2.example.com; | 711 server backend2.example.com; |
728 | 712 |
729 sticky cookie srv_id expires=1h domain=.example.com path=/; | 713 sticky_cookie_insert srv_id expires=1h domain=example.com path=/; |
730 } | 714 } |
731 </example> | 715 </example> |
732 </para> | 716 </para> |
733 | 717 |
734 <para> | 718 <para> |
735 A request that comes from a client not yet bound to a particular server | 719 A request that comes from a client not yet bound to a particular server |
736 is passed to the server selected by the configured balancing method. | 720 is passed to the server selected by the configured balancing method. |
737 Further requests from the same client are passed to the same server. | 721 Further requests from the same client are passed to the same server. |
738 If the designated server cannot process a request, the new server is | 722 If a request cannot be processed by the bound server, the new server |
739 selected as if the client has not been bound yet. | 723 is selected as if the client was not yet bound. |
740 </para> | 724 </para> |
741 | 725 |
742 <para> | 726 <para> |
743 The first parameter sets the name of the cookie to be set or inspected. | 727 Information about the bound server is kept in an HTTP cookie. |
728 The first parameter sets the name of the cookie to be inserted or inspected. | |
744 Additional parameters may be as follows: | 729 Additional parameters may be as follows: |
745 <list type="tag"> | 730 <list type="tag"> |
746 | 731 |
747 <tag-name><literal>expires</literal></tag-name> | 732 <tag-name><literal>expires</literal></tag-name> |
748 <tag-desc> | 733 <tag-desc> |
749 Sets the time for which a browser should keep the cookie. | 734 Sets the time for which a browser should keep the cookie. |
750 The special value <literal>max</literal> will cause the cookie to expire on | 735 The parameter <literal>max</literal> will cause the cookie to expire on |
751 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | 736 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. |
752 This is the maximum time understood by old browsers. | 737 This is the maximum time understood by old browsers. |
753 If the parameter is not specified, it will cause the cookie to expire at | 738 If the parameter is not specified, it will cause the cookie to expire at |
754 the end of a browser session. | 739 the end of a browser session. |
755 </tag-desc> | 740 </tag-desc> |
767 </list> | 752 </list> |
768 If any parameters are omitted, the corresponding cookie fields are not set. | 753 If any parameters are omitted, the corresponding cookie fields are not set. |
769 </para> | 754 </para> |
770 | 755 |
771 <para> | 756 <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> | |
814 <note> | 757 <note> |
815 This directive is available as part of our <commercial_version/> only. | 758 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>]; | |
839 </note> | 759 </note> |
840 </para> | 760 </para> |
841 | 761 |
842 </directive> | 762 </directive> |
843 | 763 |
968 | 888 |
969 <tag-name> | 889 <tag-name> |
970 <literal>up=</literal></tag-name> | 890 <literal>up=</literal></tag-name> |
971 <tag-desc> | 891 <tag-desc> |
972 The opposite of the “<literal>down</literal>” parameter | 892 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 | |
980 of the <link id="server"/> directive. | 893 of the <link id="server"/> directive. |
981 </tag-desc> | 894 </tag-desc> |
982 | 895 |
983 </list> | 896 </list> |
984 | 897 |