# HG changeset patch
# User Vladimir Homutov <vl@nginx.com>
# Date 1380113688 -14400
# Node ID edd50563435721d38b53369e0d42767c6b335989
# Parent  5e84ce26c7a7d5ffe98834a600c585caa3c99f0f
Documented the "sticky" directive.

diff -r 5e84ce26c7a7 -r edd505634357 xml/en/docs/http/ngx_http_upstream_module.xml
--- a/xml/en/docs/http/ngx_http_upstream_module.xml	Mon Sep 23 14:22:57 2013 +0000
+++ b/xml/en/docs/http/ngx_http_upstream_module.xml	Wed Sep 25 16:54:48 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="10">
+        rev="11">
 
 <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,6 +701,58 @@
 </directive>
 
 
+<directive name="sticky">
+<syntax><literal>route</literal> <value>variable</value> ...</syntax>
+<default/>
+<context>upstream</context>
+
+<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 bound server, the new server
+is selected as if the client was not yet bound.
+</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>]
@@ -893,6 +953,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.