nginx-site: xml/en/docs/http/ngx_http_upstream

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1001:35ae9ded0465

Updated the "sticky" directive description. The "sticky_cookie_insert" directive is deprecated. The "sticky cookie" provides the same functionality.

author	Vladimir Homutov <vl@nginx.com>
date	Thu, 03 Oct 2013 17:02:58 +0400
parents	a060ab6fb4be
children	271e735e4576

comparison

equal deleted inserted replaced

-:88c30759f2ff
+:35ae9ded0465
 <!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">
 <module name="Module ngx_http_upstream_module"
 link="/en/docs/http/ngx_http_upstream_module.html"
 lang="en"
-rev="11">
+rev="12">
 <section id="summary">
 <para>
 The <literal>ngx_http_upstream_module</literal> module
 </directive>
 <directive name="sticky">
+<syntax><literal>cookie</literal> <value>name</value>
+[<literal>expires=</literal><value>time</value>]
+[<literal>domain=</literal><value>domain</value>]
+[<literal>path=</literal><value>path</value>]</syntax>
 <syntax><literal>route</literal> <value>variable</value> ...</syntax>
 <default/>
 <context>upstream</context>
+<appeared-in>1.5.7</appeared-in>
-<para>
-Enables session affinity, which causes requests that contain route to the
-server to be passed to this server in a group of servers.
-Example:
-<example>
-map $cookie_JSESSIONID $route_cookie {
-~.+\.(?P&lt;route>\w+)$ $route;
-}
-map $request_uri $route_uri {
-~jsessionid=.+\.(?P&lt;route>\w+)$ $route;
-}
-upstream backend {
-server backend1.example.com route=a;
-server backend2.example.com route=b;
-sticky route $route_cookie $route_uri;
-}
-</example>
-Here, the “<literal>JSESSIONID</literal>” cookie is inspected for a server
-route first, and if not found, the route from the URI is used.
-</para>
-<para>
-A request that does not contain a server route is passed to the server
-selected by the configured balancing method.
-If a request cannot be processed by the designated server, the new server
-is selected as if the client has not been bound yet.
-</para>
-<para>
-The directive specifies variables that are examined for the route.
-This route is compared with routes specified in the <link id="server"/>
-directives.
-The first non-empty variable is used for server search.
-</para>
-<para>
-<note>
-This directive is available as part of our <commercial_version/> only.
-</note>
-</para>
-</directive>
-<directive name="sticky_cookie_insert">
-<syntax><value>name</value>
-[<literal>expires=</literal><value>time</value>]
-[<literal>domain=</literal><value>host</value>]
-[<literal>path=</literal><value>path</value>]</syntax>
-<default/>
-<context>upstream</context>
 <para>
 Enables session affinity, which causes requests from the same client to be
 passed to the same server in a group of servers.
-Example:
+Two methods are available,
+<literal>cookie</literal> and <literal>route</literal>.
+</para>
+<para>
+When the <literal>cookie</literal> method is used, information about the
+designated server is passed in an HTTP cookie:
 <example>
 upstream backend {
 server backend1.example.com;
 server backend2.example.com;
-sticky_cookie_insert srv_id expires=1h domain=example.com path=/;
+sticky cookie srv_id expires=1h domain=.example.com path=/;
 }
 </example>
 </para>
 <para>
 A request that comes from a client not yet bound to a particular server
 is passed to the server selected by the configured balancing method.
 Further requests from the same client are passed to the same server.
-If a request cannot be processed by the designated server, the new server
+If the designated server cannot process a request, the new server is
-is selected as if the client has not been bound yet.
+selected as if the client has not been bound yet.
 </para>
 <para>
-Information about the bound server is kept in an HTTP cookie.
+The first parameter sets the name of the cookie to be set or inspected.
-The first parameter sets the name of the cookie to be inserted or inspected.
 Additional parameters may be as follows:
 <list type="tag">
 <tag-name><literal>expires</literal></tag-name>
 <tag-desc>
 Sets the time for which a browser should keep the cookie.
-The parameter <literal>max</literal> will cause the cookie to expire on
+The special value <literal>max</literal> will cause the cookie to expire on
 “<literal>31 Dec 2037 23:55:55 GMT</literal>”.
 This is the maximum time understood by old browsers.
 If the parameter is not specified, it will cause the cookie to expire at
 the end of a browser session.
 </tag-desc>
 </list>
 If any parameters are omitted, the corresponding cookie fields are not set.
 </para>
 <para>
+When the <literal>route</literal> method is used, proxied server assigns
+client a route on receipt of the first request.
+All subsequent requests from this client will carry routing information
+in a cookie or URI.
+This information is compared with the “<literal>route</literal>” parameter
+of the <link id="server"/> directive to identify the server to which the
+request should be proxied.
+If the designated server cannot process a request, the new server is
+selected by the configured balancing method as if there is no routing
+information in the request.
+</para>
+<para>
+The parameters of the <literal>route</literal> method specify variables that
+may contain routing information.
+The first non-empty variable is used to find the matching server.
+</para>
+<para>
+Example:
+<example>
+map $cookie_jsessionid $route_cookie {
+~.+\.(?P&lt;route>\w+)$ $route;
+}
+map $request_uri $route_uri {
+~jsessionid=.+\.(?P&lt;route>\w+)$ $route;
+}
+upstream backend {
+server backend1.example.com route=a;
+server backend2.example.com route=b;
+sticky route $route_cookie $route_uri;
+}
+</example>
+Here, the route is taken from the “<literal>JSESSIONID</literal>” cookie
+if present in a request.
+Otherwise, the route from the URI is used.
+</para>
+<para>
 <note>
 This directive is available as part of our <commercial_version/> only.
+</note>
+</para>
+</directive>
+<directive name="sticky_cookie_insert">
+<syntax><value>name</value>
+[<literal>expires=</literal><value>time</value>]
+[<literal>domain=</literal><value>domain</value>]
+[<literal>path=</literal><value>path</value>]</syntax>
+<default/>
+<context>upstream</context>
+<para>
+This directive is obsolete since version 1.5.7.
+An equivalent
+<link id="sticky"/> directive with a new syntax should be used instead:
+<note>
+<literal>sticky cookie</literal> <value>name</value>
+[<literal>expires=</literal><value>time</value>]
+[<literal>domain=</literal><value>domain</value>]
+[<literal>path=</literal><value>path</value>];
 </note>
 </para>
 </directive>

Mercurial > hg > nginx-site

comparison xml/en/docs/http/ngx_http_upstream_module.xml @ 1001:35ae9ded0465