Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1125:9a95b9026a16
Upstream: reallocated the "queue" directive.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Fri, 21 Mar 2014 10:50:24 +0400 |
parents | d790333947f4 |
children | 2e28d1c4a0a2 |
comparison
equal
deleted
inserted
replaced
1124:d790333947f4 | 1125:9a95b9026a16 |
---|---|
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="16"> | 13 rev="17"> |
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 |
742 </para> | 742 </para> |
743 | 743 |
744 </directive> | 744 </directive> |
745 | 745 |
746 | 746 |
747 <directive name="sticky"> | |
748 <syntax><literal>cookie</literal> <value>name</value> | |
749 [<literal>expires=</literal><value>time</value>] | |
750 [<literal>domain=</literal><value>domain</value>] | |
751 [<literal>path=</literal><value>path</value>]</syntax> | |
752 <syntax><literal>route</literal> <value>variable</value> ...</syntax> | |
753 <default/> | |
754 <context>upstream</context> | |
755 <appeared-in>1.5.7</appeared-in> | |
756 | |
757 <para> | |
758 Enables session affinity, which causes requests from the same client to be | |
759 passed to the same server in a group of servers. | |
760 Two methods are available, | |
761 <literal>cookie</literal> and <literal>route</literal>. | |
762 </para> | |
763 | |
764 <para> | |
765 When the <literal>cookie</literal> method is used, information about the | |
766 designated server is passed in an HTTP cookie: | |
767 <example> | |
768 upstream backend { | |
769 server backend1.example.com; | |
770 server backend2.example.com; | |
771 | |
772 sticky cookie srv_id expires=1h domain=.example.com path=/; | |
773 } | |
774 </example> | |
775 </para> | |
776 | |
777 <para> | |
778 A request that comes from a client not yet bound to a particular server | |
779 is passed to the server selected by the configured balancing method. | |
780 Further requests from the same client are passed to the same server. | |
781 If the designated server cannot process a request, the new server is | |
782 selected as if the client has not been bound yet. | |
783 </para> | |
784 | |
785 <para> | |
786 The first parameter sets the name of the cookie to be set or inspected. | |
787 Additional parameters may be as follows: | |
788 <list type="tag"> | |
789 | |
790 <tag-name><literal>expires</literal></tag-name> | |
791 <tag-desc> | |
792 Sets the time for which a browser should keep the cookie. | |
793 The special value <literal>max</literal> will cause the cookie to expire on | |
794 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | |
795 This is the maximum time understood by old browsers. | |
796 If the parameter is not specified, it will cause the cookie to expire at | |
797 the end of a browser session. | |
798 </tag-desc> | |
799 | |
800 <tag-name><literal>domain</literal></tag-name> | |
801 <tag-desc> | |
802 Defines the domain for which the cookie is set. | |
803 </tag-desc> | |
804 | |
805 <tag-name><literal>path</literal></tag-name> | |
806 <tag-desc> | |
807 Defines the path for which the cookie is set. | |
808 </tag-desc> | |
809 | |
810 </list> | |
811 If any parameters are omitted, the corresponding cookie fields are not set. | |
812 </para> | |
813 | |
814 <para> | |
815 When the <literal>route</literal> method is used, proxied server assigns | |
816 client a route on receipt of the first request. | |
817 All subsequent requests from this client will carry routing information | |
818 in a cookie or URI. | |
819 This information is compared with the “<literal>route</literal>” parameter | |
820 of the <link id="server"/> directive to identify the server to which the | |
821 request should be proxied. | |
822 If the designated server cannot process a request, the new server is | |
823 selected by the configured balancing method as if there is no routing | |
824 information in the request. | |
825 </para> | |
826 | |
827 <para> | |
828 The parameters of the <literal>route</literal> method specify variables that | |
829 may contain routing information. | |
830 The first non-empty variable is used to find the matching server. | |
831 </para> | |
832 | |
833 <para> | |
834 Example: | |
835 <example> | |
836 map $cookie_jsessionid $route_cookie { | |
837 ~.+\.(?P<route>\w+)$ $route; | |
838 } | |
839 | |
840 map $request_uri $route_uri { | |
841 ~jsessionid=.+\.(?P<route>\w+)$ $route; | |
842 } | |
843 | |
844 upstream backend { | |
845 server backend1.example.com route=a; | |
846 server backend2.example.com route=b; | |
847 | |
848 sticky route $route_cookie $route_uri; | |
849 } | |
850 </example> | |
851 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie | |
852 if present in a request. | |
853 Otherwise, the route from the URI is used. | |
854 </para> | |
855 | |
856 <para> | |
857 <note> | |
858 This directive is available as part of our <commercial_version/>. | |
859 </note> | |
860 </para> | |
861 | |
862 </directive> | |
863 | |
864 | |
865 <directive name="sticky_cookie_insert"> | |
866 <syntax><value>name</value> | |
867 [<literal>expires=</literal><value>time</value>] | |
868 [<literal>domain=</literal><value>domain</value>] | |
869 [<literal>path=</literal><value>path</value>]</syntax> | |
870 <default/> | |
871 <context>upstream</context> | |
872 | |
873 <para> | |
874 This directive is obsolete since version 1.5.7. | |
875 An equivalent | |
876 <link id="sticky"/> directive with a new syntax should be used instead: | |
877 <note> | |
878 <literal>sticky cookie</literal> <value>name</value> | |
879 [<literal>expires=</literal><value>time</value>] | |
880 [<literal>domain=</literal><value>domain</value>] | |
881 [<literal>path=</literal><value>path</value>]; | |
882 </note> | |
883 </para> | |
884 | |
885 </directive> | |
886 | |
887 | |
888 <directive name="queue"> | 747 <directive name="queue"> |
889 <syntax> | 748 <syntax> |
890 <value>number</value> | 749 <value>number</value> |
891 [<literal>timeout</literal>=<value>time</value>]</syntax> | 750 [<literal>timeout</literal>=<value>time</value>]</syntax> |
892 <default/> | 751 <default/> |
918 </para> | 777 </para> |
919 | 778 |
920 </directive> | 779 </directive> |
921 | 780 |
922 | 781 |
782 <directive name="sticky"> | |
783 <syntax><literal>cookie</literal> <value>name</value> | |
784 [<literal>expires=</literal><value>time</value>] | |
785 [<literal>domain=</literal><value>domain</value>] | |
786 [<literal>path=</literal><value>path</value>]</syntax> | |
787 <syntax><literal>route</literal> <value>variable</value> ...</syntax> | |
788 <default/> | |
789 <context>upstream</context> | |
790 <appeared-in>1.5.7</appeared-in> | |
791 | |
792 <para> | |
793 Enables session affinity, which causes requests from the same client to be | |
794 passed to the same server in a group of servers. | |
795 Two methods are available, | |
796 <literal>cookie</literal> and <literal>route</literal>. | |
797 </para> | |
798 | |
799 <para> | |
800 When the <literal>cookie</literal> method is used, information about the | |
801 designated server is passed in an HTTP cookie: | |
802 <example> | |
803 upstream backend { | |
804 server backend1.example.com; | |
805 server backend2.example.com; | |
806 | |
807 sticky cookie srv_id expires=1h domain=.example.com path=/; | |
808 } | |
809 </example> | |
810 </para> | |
811 | |
812 <para> | |
813 A request that comes from a client not yet bound to a particular server | |
814 is passed to the server selected by the configured balancing method. | |
815 Further requests from the same client are passed to the same server. | |
816 If the designated server cannot process a request, the new server is | |
817 selected as if the client has not been bound yet. | |
818 </para> | |
819 | |
820 <para> | |
821 The first parameter sets the name of the cookie to be set or inspected. | |
822 Additional parameters may be as follows: | |
823 <list type="tag"> | |
824 | |
825 <tag-name><literal>expires</literal></tag-name> | |
826 <tag-desc> | |
827 Sets the time for which a browser should keep the cookie. | |
828 The special value <literal>max</literal> will cause the cookie to expire on | |
829 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | |
830 This is the maximum time understood by old browsers. | |
831 If the parameter is not specified, it will cause the cookie to expire at | |
832 the end of a browser session. | |
833 </tag-desc> | |
834 | |
835 <tag-name><literal>domain</literal></tag-name> | |
836 <tag-desc> | |
837 Defines the domain for which the cookie is set. | |
838 </tag-desc> | |
839 | |
840 <tag-name><literal>path</literal></tag-name> | |
841 <tag-desc> | |
842 Defines the path for which the cookie is set. | |
843 </tag-desc> | |
844 | |
845 </list> | |
846 If any parameters are omitted, the corresponding cookie fields are not set. | |
847 </para> | |
848 | |
849 <para> | |
850 When the <literal>route</literal> method is used, proxied server assigns | |
851 client a route on receipt of the first request. | |
852 All subsequent requests from this client will carry routing information | |
853 in a cookie or URI. | |
854 This information is compared with the “<literal>route</literal>” parameter | |
855 of the <link id="server"/> directive to identify the server to which the | |
856 request should be proxied. | |
857 If the designated server cannot process a request, the new server is | |
858 selected by the configured balancing method as if there is no routing | |
859 information in the request. | |
860 </para> | |
861 | |
862 <para> | |
863 The parameters of the <literal>route</literal> method specify variables that | |
864 may contain routing information. | |
865 The first non-empty variable is used to find the matching server. | |
866 </para> | |
867 | |
868 <para> | |
869 Example: | |
870 <example> | |
871 map $cookie_jsessionid $route_cookie { | |
872 ~.+\.(?P<route>\w+)$ $route; | |
873 } | |
874 | |
875 map $request_uri $route_uri { | |
876 ~jsessionid=.+\.(?P<route>\w+)$ $route; | |
877 } | |
878 | |
879 upstream backend { | |
880 server backend1.example.com route=a; | |
881 server backend2.example.com route=b; | |
882 | |
883 sticky route $route_cookie $route_uri; | |
884 } | |
885 </example> | |
886 Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie | |
887 if present in a request. | |
888 Otherwise, the route from the URI is used. | |
889 </para> | |
890 | |
891 <para> | |
892 <note> | |
893 This directive is available as part of our <commercial_version/>. | |
894 </note> | |
895 </para> | |
896 | |
897 </directive> | |
898 | |
899 | |
900 <directive name="sticky_cookie_insert"> | |
901 <syntax><value>name</value> | |
902 [<literal>expires=</literal><value>time</value>] | |
903 [<literal>domain=</literal><value>domain</value>] | |
904 [<literal>path=</literal><value>path</value>]</syntax> | |
905 <default/> | |
906 <context>upstream</context> | |
907 | |
908 <para> | |
909 This directive is obsolete since version 1.5.7. | |
910 An equivalent | |
911 <link id="sticky"/> directive with a new syntax should be used instead: | |
912 <note> | |
913 <literal>sticky cookie</literal> <value>name</value> | |
914 [<literal>expires=</literal><value>time</value>] | |
915 [<literal>domain=</literal><value>domain</value>] | |
916 [<literal>path=</literal><value>path</value>]; | |
917 </note> | |
918 </para> | |
919 | |
920 </directive> | |
921 | |
922 | |
923 <directive name="upstream_conf"> | 923 <directive name="upstream_conf"> |
924 <syntax/> | 924 <syntax/> |
925 <default/> | 925 <default/> |
926 <context>location</context> | 926 <context>location</context> |
927 | 927 |