Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1125:9a95b9026a16

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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&lt;route>\w+)$ $route;
838 }
839
840 map $request_uri $route_uri {
841 ~jsessionid=.+\.(?P&lt;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&lt;route>\w+)$ $route;
873 }
874
875 map $request_uri $route_uri {
876 ~jsessionid=.+\.(?P&lt;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