--- a/xml/en/docs/http/ngx_http_upstream_module.xml	Thu Jul 10 15:33:59 2014 +0400
+++ b/xml/en/docs/http/ngx_http_upstream_module.xml	Thu Jul 17 18:39:52 2014 +0400
@@ -10,7 +10,7 @@
 <module name="Module ngx_http_upstream_module"
         link="/en/docs/http/ngx_http_upstream_module.html"
         lang="en"
-        rev="27">
+        rev="28">
 
 <section id="summary">
 
@@ -53,20 +53,20 @@
 available as part of our
 <commercial_version>commercial subscription</commercial_version>:
 <example>
-upstream <emphasis>appservers</emphasis> {
-    zone appservers 64k;
+upstream <emphasis>dynamic</emphasis> {
+    zone upstream_dynamic 64k;
 
-    server appserv1.example.com      weight=5;
-    server appserv2.example.com:8080 fail_timeout=5s slow_start=30s;
+    server backend1.example.com      weight=5;
+    server backend2.example.com:8080 fail_timeout=5s slow_start=30s;
     server 192.0.2.1                 max_fails=3;
 
-    server reserve1.example.com:8080 backup;
-    server reserve2.example.com:8080 backup;
+    server backup1.example.com:8080  backup;
+    server backup2.example.com:8080  backup;
 }
 
 server {
     location / {
-        proxy_pass http://<emphasis>appservers</emphasis>;
+        proxy_pass http://<emphasis>dynamic</emphasis>;
         health_check;
     }
 
@@ -826,11 +826,19 @@
 
 
 <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>
+<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>
+<syntax>
+    <literal>learn</literal>
+    <literal>create=</literal><value>$variable</value>
+    <literal>lookup=</literal><value>$variable</value>
+    <literal>zone=</literal><value>name</value>:<value>size</value>
+    [<literal>timeout=</literal><value>time</value>]</syntax>
 <default/>
 <context>upstream</context>
 <appeared-in>1.5.7</appeared-in>
@@ -838,13 +846,14 @@
 <para>
 Enables session affinity, which causes requests from the same client to be
 passed to the same server in a group of servers.
-Two methods are available,
-<literal>cookie</literal> and <literal>route</literal>.
-</para>
+Three methods are available:
+<list type="tag">
+<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name>
+<tag-desc>
 
 <para>
 When the <literal>cookie</literal> method is used, information about the
-designated server is passed in an HTTP cookie:
+designated server is passed in an HTTP cookie generated by nginx:
 <example>
 upstream backend {
     server backend1.example.com;
@@ -858,7 +867,7 @@
 <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.
+Further requests with this cookie will be passed to the designated server.
 If the designated server cannot process a request, the new server is
 selected as if the client has not been bound yet.
 </para>
@@ -890,6 +899,10 @@
 </list>
 If any parameters are omitted, the corresponding cookie fields are not set.
 </para>
+</tag-desc>
+
+<tag-name id="sticky_route"><literal>route</literal></tag-name>
+<tag-desc>
 
 <para>
 When the <literal>route</literal> method is used, proxied server assigns
@@ -933,6 +946,54 @@
 Otherwise, the route from the URI is used.
 </para>
 
+</tag-desc>
+
+<tag-name id="sticky_learn"><literal>learn</literal></tag-name>
+<tag-desc>
+<para>
+When the <literal>learn</literal> method (1.7.1) is used, nginx
+analyzes upstream server responses and learns server-initiated sessions
+usually passed in an HTTP cookie.
+<example>
+upstream backend {
+   server backend1.example.com:8080;
+   server backend2.example.com:8081;
+
+   sticky learn
+          create=$upstream_cookie_sessionid
+          lookup=$cookie_sessionid
+          zone=client_sessions:1m;
+}
+</example>
+
+In the example, the upstream server creates a session by setting the
+cookie “<literal>SESSIONID</literal>” in the response.
+Further requests with this cookie will be passed to the same server.
+If the server cannot process the request, the new server is
+selected as if the client has not been bound yet.
+</para>
+
+<para>
+The parameters <literal>create</literal> and <literal>lookup</literal>
+specify variables that indicate how new sessions are created and existing
+sessions are searched, respectively.
+Both parameters may be specified more than once, in which case the first
+non-empty variable is used.
+</para>
+
+<para>
+Sessions are stored in a shared memory zone, whose <value>name</value> and
+<value>size</value> are configured by the <literal>zone</literal> parameter.
+One megabyte zone can store about 8000 sessions on the 64-bit platform.
+The sessions that are not accessed during the time specified by the
+<literal>timeout</literal> parameter get removed from the zone.
+By default, <literal>timeout</literal> is set to 10 minutes.
+</para>
+
+</tag-desc>
+</list>
+</para>
+
 <para>
 <note>
 This directive is available as part of our
@@ -982,23 +1043,18 @@
 Configuration commands can be used to:
 <list type="bullet">
 
-<listitem>view all primary or backup servers in a group;</listitem>
-
-<listitem>view an individual server;</listitem>
+<listitem>view the group configuration;</listitem>
 
-<listitem>modify an individual server;</listitem>
+<listitem>view, modify, or remove an individual server;</listitem>
 
-<listitem>add a new server (see the note below);</listitem>
-
-<listitem>remove an individual server.</listitem>
+<listitem>add a new server.</listitem>
 
 </list>
 <note>
-As noted in the <link id="server"/> directive, specifying a server
-as a domain name may result in several servers being added to the group.
 Since addresses in a group are not required to be unique, individual
-servers in a group can be uniquely referenced to only by their ID.
-IDs are assigned automatically and shown on viewing of the group configuration.
+servers in a group are referenced by their IDs.
+IDs are assigned automatically and shown when adding a new server
+or viewing the group configuration.
 </note>
 </para>
 
@@ -1006,7 +1062,7 @@
 A configuration command consists of parameters passed as request arguments,
 for example:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers
+http://127.0.0.1/upstream_conf?upstream=dynamic
 </example>
 </para>
 
@@ -1018,34 +1074,36 @@
 <tag-name>
 <literal>upstream=</literal><value>name</value></tag-name>
 <tag-desc>
-Selects a group.
+Selects a group to work with.
 This parameter is mandatory.
 </tag-desc>
 
 <tag-name>
-<literal>backup=</literal>
-</tag-name>
-<tag-desc>
-If not set, selects primary servers in the group.
-If set, selects backup servers in the group.
-</tag-desc>
-
-<tag-name>
 <literal>id=</literal><value>number</value></tag-name>
 <tag-desc>
-Selects an individual primary or backup server in the group.
+Selects an individual server for viewing, modifying, or removing.
 </tag-desc>
 
 <tag-name>
 <literal>remove=</literal></tag-name>
 <tag-desc>
-Removes an individual primary or backup server from the group.
+Removes an individual server from the group.
 </tag-desc>
 
 <tag-name>
 <literal>add=</literal></tag-name>
 <tag-desc>
-Adds a new primary or backup server to the group.
+Adds a new server to the group.
+</tag-desc>
+
+<tag-name>
+<literal>backup=</literal></tag-name>
+<tag-desc>
+Required to add a backup server.
+<note>
+Before version 1.7.2, <literal>backup=</literal>
+was also required to view, modify, or remove existing backup servers.
+</note>
 </tag-desc>
 
 <tag-name>
@@ -1053,6 +1111,17 @@
 <tag-desc>
 Same as the “<literal>address</literal>” parameter
 of the <link id="server"/> directive.
+<para>
+When adding a server, it is possible to specify it as a domain name.
+In this case, changes of the IP addresses that correspond to a domain name
+will be monitored and automatically applied to the upstream
+configuration without the need of restarting nginx (1.7.2).
+This requires the
+<link doc="ngx_http_core_module.xml" id="resolver"/> directive in the
+<link doc="ngx_http_core_module.xml" id="http"/> block.
+See also
+the <link id="resolve"/> parameter of the <link id="server"/> directive.
+</para>
 </tag-desc>
 
 <tag-name>
@@ -1106,96 +1175,71 @@
 
 </list>
 
-The first three parameters select a target the command applies to.
-Without other parameters, the command shows configuration of the selected
-target.
+The first two parameters select an object.
+This can be either the whole group or an individual server.
+Without other parameters, the configuration of the selected
+group or server is shown.
 </para>
 
 <para>
-For example, to view the primary servers in the group, send:
+For example, to view the configuration of the whole group, send:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers
+http://127.0.0.1/upstream_conf?upstream=dynamic
 </example>
 
-To view the backup servers in the group, send:
-<example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=
-</example>
-
-To view an individual primary server in the group, send:
+To view the configuration of an individual server, also specify its ID:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42
-</example>
-
-To view an individual backup server in the group, send:
-<example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42
+http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42
 </example>
 </para>
 
 <para>
-To add a new primary or backup server to the group,
+To add a new server,
 specify its address in the “<literal>server=</literal>” parameter.
 Without other parameters specified, a server will be added with other
 parameters set to their default values (see the <link id="server"/> directive).
 </para>
 
 <para>
-For example, to add a new primary server to the group, send:
+For example, to add a new primary server, send:
 <example>
-http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;server=127.0.0.1:8080
+http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080
 </example>
 
-To add a new backup server to the group, send:
+To add a new backup server, send:
 <example>
-http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;backup=&amp;server=127.0.0.1:8080
+http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;backup=&amp;server=127.0.0.1:8080
 </example>
 
-To add a new primary server to the group,
+To add a new primary server,
 set its parameters to non-default values
 and mark it as “<literal>down</literal>”, send:
 <example>
-http://127.0.0.1/upstream_conf?add=&amp;upstream=appservers&amp;server=127.0.0.1:8080&amp;weight=2&amp;max_fails=3&amp;fail_timeout=3s&amp;down=
+http://127.0.0.1/upstream_conf?add=&amp;upstream=dynamic&amp;server=127.0.0.1:8080&amp;weight=2&amp;down=
 </example>
 </para>
 
 <para>
-To remove an individual primary or backup server from the group,
-select it with the <literal>id=</literal> parameter.
-</para>
-
-<para>
-For example, to remove an individual primary server from the group, send:
+To remove a server, specify its ID:
 <example>
-http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;id=42
-</example>
-
-To remove an individual backup server from the group, send:
-<example>
-http://127.0.0.1/upstream_conf?remove=&amp;upstream=appservers&amp;backup=&amp;id=42
+http://127.0.0.1/upstream_conf?remove=&amp;upstream=dynamic&amp;id=42
 </example>
 </para>
 
 <para>
-To modify an individual primary or backup server in the group,
-select it with the <literal>id=</literal> parameter.
-</para>
-
-<para>
-For example, to modify an individual primary server in the group
-by marking it as “<literal>down</literal>”, send:
+To mark an existing server as “<literal>down</literal>”, send:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;down=
+http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;down=
 </example>
 
-To modify the address of an individual backup server in the group, send:
+To modify the address of an existing server, send:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;backup=&amp;id=42&amp;server=192.0.2.3:8123
+http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;server=192.0.2.3:8123
 </example>
 
-To modify other parameters of an individual primary server in the group, send:
+To modify other parameters of an existing server, send:
 <example>
-http://127.0.0.1/upstream_conf?upstream=appservers&amp;id=42&amp;max_fails=3&amp;weight=4
+http://127.0.0.1/upstream_conf?upstream=dynamic&amp;id=42&amp;max_fails=3&amp;weight=4
 </example>
 
 </para>