Mercurial > hg > nginx-site
changeset 1259:954dcc02cb63
Upstream: "session learn" sticky method and upstream_conf changes.
author | Ruslan Ermilov <ru@nginx.com> |
---|---|
date | Thu, 17 Jul 2014 18:39:52 +0400 |
parents | 700487454cf2 |
children | 6e34b5716bdb |
files | xml/en/docs/http/ngx_http_upstream_module.xml xml/ru/docs/http/ngx_http_upstream_module.xml |
diffstat | 2 files changed, 444 insertions(+), 106 deletions(-) [+] |
line wrap: on
line diff
--- 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&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&id=42 -</example> - -To view an individual backup server in the group, send: -<example> -http://127.0.0.1/upstream_conf?upstream=appservers&backup=&id=42 +http://127.0.0.1/upstream_conf?upstream=dynamic&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=&upstream=appservers&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&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=&upstream=appservers&backup=&server=127.0.0.1:8080 +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&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=&upstream=appservers&server=127.0.0.1:8080&weight=2&max_fails=3&fail_timeout=3s&down= +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&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=&upstream=appservers&id=42 -</example> - -To remove an individual backup server from the group, send: -<example> -http://127.0.0.1/upstream_conf?remove=&upstream=appservers&backup=&id=42 +http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&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&id=42&down= +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&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&backup=&id=42&server=192.0.2.3:8123 +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&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&id=42&max_fails=3&weight=4 +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 </example> </para>
--- a/xml/ru/docs/http/ngx_http_upstream_module.xml Thu Jul 10 15:33:59 2014 +0400 +++ b/xml/ru/docs/http/ngx_http_upstream_module.xml Thu Jul 17 18:39:52 2014 +0400 @@ -10,7 +10,7 @@ <module name="Модуль ngx_http_upstream_module" link="/ru/docs/http/ngx_http_upstream_module.html" lang="ru" - rev="6"> + rev="28"> <section id="summary"> @@ -54,20 +54,20 @@ доступна как часть <commercial_version>коммерческой подписки</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; } @@ -832,11 +832,19 @@ <directive name="sticky"> -<syntax><literal>cookie</literal> <value>имя</value> -[<literal>expires=</literal><value>время</value>] -[<literal>domain=</literal><value>домен</value>] -[<literal>path=</literal><value>путь</value>]</syntax> -<syntax><literal>route</literal> <value>переменная</value> ...</syntax> +<syntax> + <literal>cookie</literal> <value>имя</value> + [<literal>expires=</literal><value>время</value>] + [<literal>domain=</literal><value>домен</value>] + [<literal>path=</literal><value>путь</value>]</syntax> +<syntax> + <literal>route</literal> <value>переменная</value> ...</syntax> +<syntax> + <literal>learn</literal> + <literal>create=</literal><value>$переменная</value> + <literal>lookup=</literal><value>$переменная</value> + <literal>zone=</literal><value>имя</value>:<value>размер</value> + [<literal>timeout=</literal><value>время</value>]</syntax> <default/> <context>upstream</context> <appeared-in>1.5.7</appeared-in> @@ -844,9 +852,10 @@ <para> Включает режим привязки сеансов, в котором запросы клиента будут передаваться на один и тот же сервер группы. -Доступны два метода: -<literal>cookie</literal> и <literal>route</literal>. -</para> +Доступны три метода: +<list type="tag"> +<tag-name id="sticky_cookie"><literal>cookie</literal></tag-name> +<tag-desc> <para> При использовании метода <literal>cookie</literal> информация о @@ -895,6 +904,10 @@ </list> Если пропущен тот или иной параметр, то соответствующего поля в куке не будет. </para> +</tag-desc> + +<tag-name id="sticky_route"><literal>route</literal></tag-name> +<tag-desc> <para> При использовании метода <literal>route</literal> проксируемый сервер назначает @@ -938,6 +951,55 @@ В противном случае используется маршрут из URI. </para> +</tag-desc> + +<tag-name id="sticky_learn"><literal>learn</literal></tag-name> +<tag-desc> +<para> +При использовании метода <literal>learn</literal> (1.7.1) nginx +анализирует ответы от вышестоящего сервера и запоминает +начатые им сессии, которые обычно передаются в HTTP-куке. +<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> + +В примере выше сервер группы создаёт сессию путём установки +куки “<literal>SESSIONID</literal>” в своём ответе. +Последующие запросы с этой кукой будут передаваться на этот же сервер. +Если сервер не может обработать запрос, выбирается новый +сервер как если бы клиент не имел привязки к серверу. +</para> + +<para> +Параметры <literal>create</literal> и <literal>lookup</literal> +задают переменные, в которых соответственно указывается способ +создания новых и поиска существующих сессий. +Оба параметра могут быть указаны больше одного раза +(в этом случае используется первая непустая переменная). +</para> + +<para> +Сессии хранятся в зоне разделяемой памяти, <value>имя</value> и +<value>размер</value> которой задаются параметром <literal>zone</literal>. +Зоны размером в 1 мегабайт достаточно для хранения около 8 тысяч сессий +на 64-битной платформе. +Сессии, к которым не было обращений в течение времени, заданного параметром +<literal>timeout</literal>, удаляются из зоны. +По умолчанию <literal>timeout</literal> равен 10 минутам. +</para> + +</tag-desc> +</list> +</para> + <para> <note> Эта директива доступна как часть @@ -970,6 +1032,238 @@ </directive> + +<directive name="upstream_conf"> +<syntax/> +<default/> +<context>location</context> + +<para> +Активирует HTTP-интерфейс для настройки групп серверов в содержащем location. +Доступ в location следует +<link doc="ngx_http_core_module.xml" id="satisfy">ограничить</link>. +</para> + +<para> +С помощью команд настройки можно: +<list type="bullet"> + +<listitem>просматривать конфигурацию группы;</listitem> + +<listitem> +просматривать или изменять конфигурацию, а также +удалять отдельные серверы; +</listitem> + +<listitem>добавлять новые серверы.</listitem> + +</list> +<note> +Поскольку адреса в группе не обязаны быть уникальными, +обращение к отдельным серверам в группе осуществляется по их идентификаторам. +Идентификаторы назначаются автоматически и показываются при добавлении сервера +или просмотре конфигурации группы. +</note> +</para> + +<para> +Команда настройки состоит из параметров, передаваемых в аргументах запроса, +например: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic +</example> +</para> + +<para> +Поддерживаются следующие параметры: + +<list type="tag" compact="no"> + +<tag-name> +<literal>upstream=</literal><value>имя</value></tag-name> +<tag-desc> +Выбирает группу серверов для работы. +Параметр является обязательным. +</tag-desc> + +<tag-name> +<literal>id=</literal><value>число</value></tag-name> +<tag-desc> +Выбирает отдельный сервер для просмотра, изменения или удаления. +</tag-desc> + +<tag-name> +<literal>remove=</literal></tag-name> +<tag-desc> +Удаляет выбранный сервер из группы. +</tag-desc> + +<tag-name> +<literal>add=</literal></tag-name> +<tag-desc> +Добавляет новый сервер в группу. +</tag-desc> + +<tag-name> +<literal>backup=</literal></tag-name> +<tag-desc> +Необходим для добавления запасного сервера. +<note> +До версии 1.7.2 параметр <literal>backup=</literal> требовался +также для просмотра, изменения или удаления существующих запасных серверов. +</note> +</tag-desc> + +<tag-name> +<literal>server=</literal><value>адрес</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>адрес</literal>” +директивы <link id="server"/>. +<para> +При добавлении сервер можно задать в виде доменного имени. +В этом случае любые изменения IP-адресов, соответствующих доменному имени +сервера, отслеживаются и автоматически применяются к конфигурации группы +без необходимости перезапуска nginx (1.7.2). +Для этого в блоке <link doc="ngx_http_core_module.xml" id="http"/> должна +быть задана директива <link doc="ngx_http_core_module.xml" id="resolver"/>. +См. также параметр +<link id="resolve"/> директивы <link id="server"/>. +</para> +</tag-desc> + +<tag-name> +<literal>weight=</literal><value>число</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>weight</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>max_fails=</literal><value>число</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>max_fails</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>fail_timeout=</literal><value>время</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>fail_timeout</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>slow_start=</literal><value>время</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>slow_start</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>down=</literal></tag-name> +<tag-desc> +То же, что и параметр “<literal>down</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>up=</literal></tag-name> +<tag-desc> +Параметр, обратный по значению параметру “<literal>down</literal>” +директивы <link id="server"/>. +</tag-desc> + +<tag-name> +<literal>route=</literal><value>строка</value></tag-name> +<tag-desc> +То же, что и параметр “<literal>route</literal>” +директивы <link id="server"/>. +</tag-desc> + +</list> + +Первые два параметра выбирают объект. +Объектом может быть либо группа серверов, либо отдельный сервер. +Если остальные параметры не указаны, то показывается конфигурация выбранной +группы или сервера. +</para> + +<para> +Например, команда для просмотра конфигурации всей группы +выглядит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic +</example> + +Для просмотра конфигурации отдельного сервера следует указать его идентификатор: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42 +</example> + +</para> + +<para> +Для добавления нового сервера в группу +следует указать его адрес в параметре “<literal>server=</literal>”. +Если остальные параметры не указаны, то при добавлении сервера +их значения будут установлены по умолчанию (см. директиву <link id="server"/>). +</para> + +<para> +Например, команда для добавления нового основного сервера в группу +выглядит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080 +</example> + +Добавление нового запасного сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&backup=&server=127.0.0.1:8080 +</example> + +Добавление нового основного сервера с нестандартными +значениями параметров и с пометкой его как постоянно недоступного +(“<literal>down</literal>”) происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?add=&upstream=dynamic&server=127.0.0.1:8080&weight=2&down= +</example> +</para> + +<para> +Для удаления сервера следует указать его идентификатор: +<example> +http://127.0.0.1/upstream_conf?remove=&upstream=dynamic&id=42 +</example> +</para> + +<para> +Пометка существующего сервера как постоянно недоступного +(“<literal>down</literal>”) происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&down= +</example> + +Изменение адреса существующего сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&server=192.0.2.3:8123 +</example> + +Изменение других параметров существующего сервера происходит следующим образом: +<example> +http://127.0.0.1/upstream_conf?upstream=dynamic&id=42&max_fails=3&weight=4 +</example> + +</para> + +<para> +<note> +Эта директива доступна как часть +<commercial_version>коммерческой подписки</commercial_version>. +</note> +</para> + +</directive> + </section>