Mercurial > hg > nginx-site
comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 960:48ab154edf10
Upstream: removed obsoleted directives in the "sticky" module.
The "sticky" and "sticky_log_requests" directives were removed. The sticky
feature description has been revised.
author | Vladimir Homutov <vl@nginx.com> |
---|---|
date | Thu, 08 Aug 2013 14:51:40 +0400 |
parents | 488a3f738db0 |
children | f3754c623e6b |
comparison
equal
deleted
inserted
replaced
959:fbb4cc6f8c3d | 960:48ab154edf10 |
---|---|
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="6"> | 13 rev="7"> |
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 |
687 </para> | 687 </para> |
688 | 688 |
689 </directive> | 689 </directive> |
690 | 690 |
691 | 691 |
692 <directive name="sticky"> | |
693 <syntax/> | |
694 <default/> | |
695 <context>upstream</context> | |
696 | |
697 <para> | |
698 Enables session affinity support. | |
699 The session is an object that is used to uniquely identify and maintain the | |
700 state of a client during a given period of time. | |
701 If session affinity is enabled, requests from the same client are always passed | |
702 to the same server (in a group of servers) once a session has been created. | |
703 The method that is used to create and track sessions must be specified in a | |
704 separate directive, for example, <link id="sticky_cookie_insert"/>. | |
705 <example> | |
706 upstream backend { | |
707 server backend1.example.com; | |
708 server backend2.example.com; | |
709 | |
710 sticky; | |
711 sticky_cookie_insert "sticky"; | |
712 } | |
713 | |
714 server { | |
715 location / { | |
716 proxy_pass http://backend; | |
717 } | |
718 } | |
719 </example> | |
720 The directive must be specified after the <link id="ip_hash"/> or the | |
721 <link id="least_conn"/> directives. | |
722 </para> | |
723 | |
724 <para> | |
725 When the session affinity is enabled, a request is processed as follows: | |
726 <list type="enum"> | |
727 | |
728 <listitem> | |
729 nginx looks up the session corresponding to the request. | |
730 If the session is found, the server identification data is extracted from it. | |
731 This data is used by the server selection algorithm. | |
732 </listitem> | |
733 | |
734 <listitem> | |
735 The server to process the request is chosen according to the configured | |
736 balancing method, server information from the session, and the real state of | |
737 servers in a group (such as failed, up or down). | |
738 </listitem> | |
739 | |
740 <listitem> | |
741 The request is passed to the chosen server for processing. | |
742 If the chosen server is not the one specified in the session | |
743 (for example, because it is down), the session is cleared | |
744 and the request is processed as if it had no session. | |
745 </listitem> | |
746 | |
747 <listitem> | |
748 The server returns the response. | |
749 </listitem> | |
750 | |
751 <listitem> | |
752 If there is no session for the request, a new session | |
753 is created and the server identification data is stored in it. | |
754 </listitem> | |
755 | |
756 </list> | |
757 </para> | |
758 | |
759 <para> | |
760 <note> | |
761 This directive is available as part of our <commercial_version/> only. | |
762 </note> | |
763 </para> | |
764 | |
765 </directive> | |
766 | |
767 | |
768 <directive name="sticky_cookie_insert"> | 692 <directive name="sticky_cookie_insert"> |
769 <syntax><value>name</value> | 693 <syntax><value>name</value> |
770 [<literal>expires=</literal><value>time</value>] | 694 [<literal>expires=</literal><value>time</value>] |
771 [<literal>domain=</literal><value>host</value>] | 695 [<literal>domain=</literal><value>host</value>] |
772 [<literal>path=</literal><value>path</value>]</syntax> | 696 [<literal>path=</literal><value>path</value>]</syntax> |
773 <default/> | 697 <default/> |
774 <context>upstream</context> | 698 <context>upstream</context> |
775 | 699 |
776 <para> | 700 <para> |
777 Enables and configures the session tracking method that is based on keeping | 701 Enables session affinity that causes requests from the same client to be |
778 session information in HTTP cookies. | 702 passed to the same server in a group of servers. |
779 The directive must be specified after the <link id="ip_hash"/> or the | |
780 <link id="least_conn"/> directives. | |
781 Example: | 703 Example: |
782 <example> | 704 <example> |
783 sticky_cookie_insert "srv_id" "expires=1h 7m" domain=example.com path=/; | 705 upstream backend { |
784 </example> | 706 server backend1.example.com; |
707 server backend2.example.com; | |
708 | |
709 sticky_cookie_insert srv_id expires=1h domain=example.com path=/; | |
710 } | |
711 </example> | |
712 </para> | |
713 | |
714 <para> | |
715 A request that comes from a client not yet bound to a particular server | |
716 is passed to the server selected by the configured balancing method. | |
717 Further requests from the same client are passed to the same server. | |
718 If a request cannot be processed by the bound server, the new server | |
719 is selected as if the client was not yet bound. | |
720 </para> | |
721 | |
722 <para> | |
723 Information about the bound server is kept in HTTP cookie. | |
785 The first parameter sets the name of the cookie to be inserted or inspected. | 724 The first parameter sets the name of the cookie to be inserted or inspected. |
786 Additional parameters may be as follows: | 725 Additional parameters may be as follows: |
787 <list type="tag"> | 726 <list type="tag"> |
788 | 727 |
789 <tag-name><literal>expires</literal></tag-name> | 728 <tag-name><literal>expires</literal></tag-name> |
790 <tag-desc> | 729 <tag-desc> |
791 Sets the time for which a browser should keep the cookie. | 730 Sets the time for which a browser should keep the cookie. |
792 The parameter “<literal>max</literal>” sets the time to | 731 The parameter <literal>max</literal> will cause the cookie to expire on |
793 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. | 732 “<literal>31 Dec 2037 23:55:55 GMT</literal>”. |
794 This is the maximum time understood by old browsers. | 733 This is the maximum time understood by old browsers. |
734 If the parameter is not specified, it will cause the cookie to expire at | |
735 the end of a browser session. | |
795 </tag-desc> | 736 </tag-desc> |
796 | 737 |
797 <tag-name><literal>domain</literal></tag-name> | 738 <tag-name><literal>domain</literal></tag-name> |
798 <tag-desc> | 739 <tag-desc> |
799 Defines the domain for which the cookie is set. | 740 Defines the domain for which the cookie is set. |
804 Defines the path for which the cookie is set. | 745 Defines the path for which the cookie is set. |
805 </tag-desc> | 746 </tag-desc> |
806 | 747 |
807 </list> | 748 </list> |
808 If some parameter is omitted, the corresponding cookie field is not set. | 749 If some parameter is omitted, the corresponding cookie field is not set. |
809 </para> | |
810 | |
811 <para> | |
812 <note> | |
813 This directive is available as part of our <commercial_version/> only. | |
814 </note> | |
815 </para> | |
816 | |
817 </directive> | |
818 | |
819 | |
820 <directive name="sticky_log_requests"> | |
821 <syntax><literal>debug</literal> | | |
822 <literal>info</literal> | | |
823 <literal>notice</literal> | | |
824 <literal>warn</literal> | | |
825 <literal>error</literal></syntax> | |
826 <default/> | |
827 <context>upstream</context> | |
828 | |
829 <para> | |
830 Enables logging of session-related operations and sets the desired | |
831 logging level. | |
832 </para> | 750 </para> |
833 | 751 |
834 <para> | 752 <para> |
835 <note> | 753 <note> |
836 This directive is available as part of our <commercial_version/> only. | 754 This directive is available as part of our <commercial_version/> only. |