Mercurial > hg > nginx-site
changeset 1026:3056640d5022
Upstream: documented new "sticky" features.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Wed, 23 Oct 2013 15:19:38 +0400 |
parents | 36cf06691ff1 |
children | dd64ce140de2 |
files | xml/en/docs/http/ngx_http_upstream_module.xml |
diffstat | 1 files changed, 98 insertions(+), 11 deletions(-) [+] |
line wrap: on
line diff
--- a/xml/en/docs/http/ngx_http_upstream_module.xml Wed Dec 11 09:17:55 2013 +0400 +++ b/xml/en/docs/http/ngx_http_upstream_module.xml Wed Oct 23 15:19:38 2013 +0400 @@ -10,7 +10,7 @@ <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"> @@ -203,6 +203,14 @@ the <link id="ip_hash"/> directive. </tag-desc> +<tag-name><literal>route</literal>=<value>string</value></tag-name> +<tag-desc> +sets the server route name. +<note> +This functionality is available as part of our <commercial_version/> only. +</note> +</tag-desc> + </list> </para> @@ -693,24 +701,32 @@ </directive> -<directive name="sticky_cookie_insert"> -<syntax><value>name</value> +<directive name="sticky"> +<syntax><literal>cookie</literal> <value>name</value> [<literal>expires=</literal><value>time</value>] -[<literal>domain=</literal><value>host</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 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> @@ -719,20 +735,19 @@ 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 bound server, the new server -is selected as if the client was not yet bound. +If the designated server cannot process a request, the new server is +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 inserted or inspected. +The first parameter sets the name of the cookie to be set 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 @@ -754,6 +769,48 @@ </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<route>\w+)$ $route; +} + +map $request_uri $route_uri { + ~jsessionid=.+\.(?P<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> @@ -762,6 +819,29 @@ </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> + + <directive name="upstream_conf"> <syntax/> <default/> @@ -893,6 +973,13 @@ of the <link id="server"/> directive. </tag-desc> +<tag-name> +<literal>route=</literal><value>string</value></tag-name> +<tag-desc> +Same as the “<literal>route</literal>” parameter +of the <link id="server"/> directive. +</tag-desc> + </list> The first three parameters select a target the command applies to.