Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 960:48ab154edf10

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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.