<?xml version="1.0"?>

<!--
  Copyright (C) Igor Sysoev
  Copyright (C) Nginx, Inc.
  -->

<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd">

<module name="Модуль ngx_http_upstream_module"
        link="/ru/docs/http/ngx_http_upstream_module.html"
        lang="ru"
        rev="6">

<section id="summary">

<para>
Модуль <literal>ngx_http_upstream_module</literal>
позволяет описывать группы серверов,
которые могут использоваться в директивах
<link doc="ngx_http_proxy_module.xml" id="proxy_pass"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_pass"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_pass"/>,
<link doc="ngx_http_scgi_module.xml" id="scgi_pass"/> и
<link doc="ngx_http_memcached_module.xml" id="memcached_pass"/>.
</para>

</section>


<section id="example" name="Пример конфигурации">

<para>
<example>
upstream <emphasis>backend</emphasis> {
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

server {
    location / {
        proxy_pass http://<emphasis>backend</emphasis>;
    }
}
</example>
</para>

</section>


<section id="directives" name="Директивы">

<directive name="upstream">
<syntax block="yes"><value>название</value></syntax>
<default/>
<context>http</context>

<para>
Описывает группу серверов.
Серверы могут слушать на разных портах.
Кроме того, можно одновременно использовать серверы,
слушающие на TCP- и UNIX-сокетах.
</para>

<para>
Пример:
<example>
upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server unix:/tmp/backend3;

    server backup1.example.com  backup;
}
</example>
</para>

<para>
По умолчанию запросы распределяются по серверам циклически
(в режиме round-robin) с учётом весов серверов.
В вышеприведённом примере каждые 7 запросов будут распределены так:
5 запросов на <literal>backend1.example.com</literal>
и по одному запросу на второй и третий серверы.
Если при попытке работы с сервером происходит ошибка, то запрос
передаётся следующему серверу, и так далее до тех пор, пока не будут опробованы
все работающие серверы.
Если не удастся получить успешный ответ
ни от одного из серверов, то клиенту будет возвращён результат работы
с последним сервером.
</para>

</directive>


<directive name="server">
<syntax><value>адрес</value> [<value>параметры</value>]</syntax>
<default/>
<context>upstream</context>

<para>
Задаёт <value>адрес</value> и другие <value>параметры</value>
сервера.
Адрес может быть указан в виде доменного имени или IP-адреса,
и необязательного порта, или в виде пути UNIX-сокета, который
указывается после префикса “<literal>unix:</literal>”.
Если порт не указан, используется порт 80.
Доменное имя, которому соответствует несколько IP-адресов,
задаёт сразу несколько серверов.
</para>

<para>
Могут быть заданы следующие параметры:
<list type="tag">

<tag-name><literal>weight</literal>=<value>число</value></tag-name>
<tag-desc>
задаёт вес сервера, по умолчанию 1.
</tag-desc>

<tag-name><literal>max_fails</literal>=<value>число</value></tag-name>
<tag-desc>
задаёт число неудачных попыток работы с сервером, которые должны произойти
в промежуток времени, заданный параметром <literal>fail_timeout</literal>,
чтобы сервер считался неработающим на период времени, также заданный
параметром <literal>fail_timeout</literal>.
По умолчанию число попыток устанавливается равным 1.
Нулевое значение отключает учёт попыток.
Что считается неудачной попыткой, определяется директивами
<link doc="ngx_http_proxy_module.xml" id="proxy_next_upstream"/>,
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_next_upstream"/>,
<link doc="ngx_http_uwsgi_module.xml" id="uwsgi_next_upstream"/>,
<link doc="ngx_http_scgi_module.xml" id="scgi_next_upstream"/> и
<link doc="ngx_http_memcached_module.xml" id="memcached_next_upstream"/>.
</tag-desc>

<tag-name><literal>fail_timeout</literal>=<value>время</value></tag-name>
<tag-desc>
задаёт
<list type="bullet">

<listitem>
время, в течение которого должно произойти заданное число неудачных
попыток работы с сервером для того, чтобы сервер считался неработающим;
</listitem>

<listitem>
и время, в течение которого сервер будет считаться неработающим.
</listitem>

</list>
По умолчанию параметр равен 10 секундам.
</tag-desc>

<tag-name><literal>backup</literal></tag-name>
<tag-desc>
помечает сервер как запасной сервер.
На него будут передаваться запросы в случае, если не работают основные серверы.
</tag-desc>

<tag-name><literal>down</literal></tag-name>
<tag-desc>
помечает сервер как постоянно неработающий; используется
совместно с директивой <link id="ip_hash"/>.
</tag-desc>

</list>
</para>

<para>
Кроме того,
следующие параметры доступны как часть
<commercial_version>коммерческой подписки</commercial_version>:
<list type="tag">

<tag-name id="max_conns">
<literal>max_conns</literal>=<value>число</value>
</tag-name>
<tag-desc>
ограничивает максимальное <value>число</value> одновременных соединений
к проксируемому серверу (1.5.9).
Значение по умолчанию равно 0 и означает, что ограничения нет.
</tag-desc>

<tag-name id="resolve">
<literal>resolve</literal>
</tag-name>
<tag-desc>
отслеживает изменения IP-адресов, соответствующих доменному имени сервера,
и автоматически изменяет конфигурацию группы
без необходимости перезапуска nginx (1.5.12).
<para>
Для работы этого параметра
директива <link doc="ngx_http_core_module.xml" id="resolver"/>
должна быть задана в блоке
<link doc="ngx_http_core_module.xml" id="http"/>.
Пример:
<example>
http {
    resolver 10.0.0.1;

    upstream u {
        zone ...;
        ...
        server example.com resolve;
    }
}
</example>
</para>
</tag-desc>

</list>
</para>

</directive>


<directive name="zone">
<syntax><value>имя</value> <value>размер</value></syntax>
<default/>
<context>upstream</context>

<para>
Задаёт <value>имя</value> и <value>размер</value> зоны разделяемой памяти,
в которой хранятся конфигурация группы и рабочее состояние,
разделяемые между рабочими процессами.
В таких группах возможно изменение состава группы или
настроек отдельных серверов без необходимости перезапуска nginx.
Конфигурация доступна через специальный location,
для которого указана директива <link id="upstream_conf"/>.
</para>

<para>
<note>
Эта директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<directive name="hash">
<syntax><value>ключ</value> [<literal>consistent</literal>]</syntax>
<default/>
<context>upstream</context>
<appeared-in>1.7.2</appeared-in>

<para>
Задаёт метод балансировки нагрузки для группы, при котором
соответствие клиента серверу определяется при помощи
хэшированного значения <value>ключа</value>.
В качестве <value>ключа</value> может использоваться
текст, переменные и их комбинации.
Следует отметить, что любое добавление или удаление серверов в группе
может привести к перераспределению большинства ключей на другие серверы.
Метод совместим с библиотекой Perl
<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached">Cache::Memcached</link>.
</para>

<para>
Если задан параметр <literal>consistent</literal>, то вместо
вышеописанного метода будет использоваться метод консистентного хэширования
<link url="http://www.last.fm/user/RJ/journal/2007/04/10/392555/">ketama</link>.
Метод гарантирует, что при добавлении сервера в группу или его удалении
на другие серверы будет перераспределено минимальное число ключей.
Применение метода для кэширующих серверов обеспечивает
больший процент попаданий в кэш.
Метод совместим с библиотекой Perl
<link url="http://search.cpan.org/perldoc?Cache%3A%3AMemcached%3A%3AFast">Cache::Memcached::Fast</link>
при значении параметра <value>ketama_points</value> равным 160.
</para>

</directive>


<directive name="ip_hash">
<syntax/>
<default/>
<context>upstream</context>

<para>
Задаёт для группы метод балансировки нагрузки, при котором запросы
распределяются по серверам на основе IP-адресов клиентов.
В качестве ключа для хэширования используются первые три
октета IPv4-адреса клиента или IPv6-адрес клиента целиком.
Метод гарантирует, что запросы одного и того же клиента
будут всегда передаваться на один и тот же сервер.
Если же этот сервер будет считаться неработающим,
то запросы этого клиента будут передаваться на другой сервер.
С большой долей вероятности это также будет один и тот же сервер.
<note>
IPv6-адреса поддерживаются начиная с версий 1.3.2 и 1.2.2.
</note>
</para>

<para>
Если один из серверов нужно убрать на некоторое время, то для сохранения
текущего хэширования IP-адресов клиентов этот сервер нужно пометить
параметром <literal>down</literal>.
</para>

<para>
Пример:
<example>
upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com <emphasis>down</emphasis>;
    server backend4.example.com;
}
</example>
</para>

<para>
<note>
До версий 1.3.1 и 1.2.2 для серверов, использующих метод балансировки нагрузки
<literal>ip_hash</literal>, нельзя было задать вес.
</note>
</para>

</directive>


<directive name="keepalive">
<syntax><value>соединения</value></syntax>
<default/>
<context>upstream</context>
<appeared-in>1.1.4</appeared-in>

<para>
Задействует кэш соединений для группы серверов.
</para>

<para>
Параметр <value>соединения</value> устанавливает максимальное число
неактивных постоянных соединений с серверами группы, которые будут
сохраняться в кэше каждого рабочего процесса.
При превышении этого числа наиболее давно не используемые соединения
закрываются.
<note>
Следует особо отметить, что директива <literal>keepalive</literal>
не ограничивает общее число соединений с серверами группы, которые
рабочие процессы nginx могут открыть.
Параметр <value>соединения</value> следует устанавливать достаточно
консервативно, чтобы серверы группы по-прежнему могли обрабатывать
новые входящие соединения.
</note>
</para>

<para>
Пример конфигурации группы серверов memcached с постоянными соединениями:
<example>
upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    ...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}
</example>
</para>

<para>
Для HTTP директиву
<link doc="ngx_http_proxy_module.xml" id="proxy_http_version"/>
следует установить в “<literal>1.1</literal>”,
а поле заголовка <header>Connection</header> — очистить:
<example>
upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    ...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        ...
    }
}
</example>
</para>

<para>
<note>
Хоть это и не рекомендуется, но также возможно использование постоянных
соединений с HTTP/1.0, путём передачи поля заголовка
<header>Connection: Keep-Alive</header> серверу группы.
</note>
</para>

<para>
Для работы постоянных соединений с FastCGI-серверами потребуется
включить директиву
<link doc="ngx_http_fastcgi_module.xml" id="fastcgi_keep_conn"/>:
<example>
upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    ...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
        ...
    }
}
</example>
</para>

<para>
<note>
При использовании методов балансировки нагрузки, отличных
от стандартного round-robin, следует активировать их до
директивы <literal>keepalive</literal>.
</note>

<note>
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.
</note>
</para>

</directive>


<directive name="least_conn">
<syntax/>
<default/>
<context>upstream</context>
<appeared-in>1.3.1</appeared-in>
<appeared-in>1.2.2</appeared-in>

<para>
Задаёт для группы метод балансировки нагрузки, при котором запрос
передаётся серверу с наименьшим числом активных соединений,
с учётом весов серверов.
Если подходит сразу несколько серверов, они выбираются циклически
(в режиме round-robin) с учётом их весов.
</para>

</directive>


<directive name="queue">
<syntax>
<value>число</value>
[<literal>timeout</literal>=<value>время</value>]</syntax>
<default/>
<context>upstream</context>
<appeared-in>1.5.12</appeared-in>

<para>
Если при обработке запроса невозможно сразу выбрать сервер группы
и в группе есть серверы, у которых число соединений достигло
ограничения <link id="max_conns"/>,
запрос будет помещён в очередь.
Директива задаёт максимальное число запросов, которые могут одновременно
находиться в очереди.
Если очередь переполнена
или за время, задаваемое параметром <literal>timeout</literal>,
так и не удастся выбрать сервер для передачи ему запроса,
клиенту будет возвращена ошибка.
</para>

<para>
По умолчанию параметр <literal>timeout</literal> равен 60 секундам.
</para>

<para>
<note>
Эта директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<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>
<default/>
<context>upstream</context>
<appeared-in>1.5.7</appeared-in>

<para>
Включает режим привязки сеансов, в котором запросы клиента
будут передаваться на один и тот же сервер группы.
Доступны два метода:
<literal>cookie</literal> и <literal>route</literal>.
</para>

<para>
При использовании метода <literal>cookie</literal> информация о
назначенном сервере передаётся в HTTP-куке:
<example>
upstream backend {
    server backend1.example.com;
    server backend2.example.com;

    sticky cookie srv_id expires=1h domain=.example.com path=/;
}
</example>
</para>

<para>
Запрос от клиента, ещё не привязанного к определённому серверу,
передаётся на сервер, выбранный согласно настроенному методу балансировки.
Дальнейшие запросы от этого клиента передаются на тот же сервер.
Если назначенный сервер не может обработать запрос, выбирается новый
сервер как если бы клиент не имел привязки к серверу.
</para>

<para>
Первый параметр задаёт имя куки, которую необходимо установить или проверить.
Дополнительные параметры могут быть следующими:
<list type="tag">

<tag-name><literal>expires</literal></tag-name>
<tag-desc>
Задаёт время, в течение которого браузеру необходимо хранить куку.
Специальное значение <literal>max</literal> устанавливает срок хранения куки до
31 декабря 2037 года 23:55:55 GMT.
Если параметр не указан, то время действия куки ограничивается сессией браузера.
</tag-desc>

<tag-name><literal>domain</literal></tag-name>
<tag-desc>
Задаёт домен, для которого устанавливается кука.
</tag-desc>

<tag-name><literal>path</literal></tag-name>
<tag-desc>
Задаёт путь, для которого устанавливается кука.
</tag-desc>

</list>
Если пропущен тот или иной параметр, то соответствующего поля в куке не будет.
</para>

<para>
При использовании метода <literal>route</literal> проксируемый сервер назначает
клиенту маршрут по получении первого запроса.
Все последующие запросы от этого клиента будут содержать информацию о
маршруте в куке или URI.
Эта информация сравнивается с параметром “<literal>route</literal>” директивы
<link id="server"/> для идентификации сервера, на который
следует проксировать запрос.
Если назначенный сервер не может обработать запрос, выбирается новый сервер
согласно настроенному методу балансировки как если бы в запросе не было
информации о маршруте.
</para>

<para>
Параметры метода <literal>route</literal> задают переменные, которые
могут содержать информацию о маршрутизации.
Первая непустая переменная используется для поиска соответствующего сервера.
</para>

<para>
Пример:
<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>
В этом примере маршрут берётся из куки “<literal>JSESSIONID</literal>”,
если она присутствует в запросе.
В противном случае используется маршрут из URI.
</para>

<para>
<note>
Эта директива доступна как часть
<commercial_version>коммерческой подписки</commercial_version>.
</note>
</para>

</directive>


<directive name="sticky_cookie_insert">
<syntax><value>имя</value>
[<literal>expires=</literal><value>время</value>]
[<literal>domain=</literal><value>домен</value>]
[<literal>path=</literal><value>путь</value>]</syntax>
<default/>
<context>upstream</context>

<para>
Эта директива устарела начиная с версии 1.5.7.
Вместо неё следует использовать аналогичную директиву
<link id="sticky"/> с изменённым синтаксисом:
<note>
<literal>sticky cookie</literal> <value>имя</value>
[<literal>expires=</literal><value>время</value>]
[<literal>domain=</literal><value>домен</value>]
[<literal>path=</literal><value>путь</value>];
</note>
</para>

</directive>

</section>


<section id="variables" name="Встроенные переменные">

<para>
Модуль <literal>ngx_http_upstream_module</literal>
поддерживает следующие встроенные переменные:
<list type="tag">

<tag-name id="var_upstream_addr"><var>$upstream_addr</var></tag-name>
<tag-desc>
хранит IP-адрес и порт сервера или путь к UNIX-сокету.
Если при обработке запроса были сделаны обращения к нескольким серверам,
то их адреса разделяются запятой, например,
“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock</literal>”.
Если произошло внутреннее перенаправление от одной группы серверов на другую
с помощью
<header>X-Accel-Redirect</header> или
<link doc="ngx_http_core_module.xml" id="error_page"/>,
то адреса, соответствующие разным группам серверов, разделяются двоеточием,
например,
“<literal>192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80</literal>”.
</tag-desc>

<tag-name id="var_upstream_cache_status"><var>$upstream_cache_status</var>
</tag-name>
<tag-desc>
хранит статус доступа к кэшу ответов (0.8.3).
Статус может быть одним из “<literal>MISS</literal>”,
“<literal>BYPASS</literal>”, “<literal>EXPIRED</literal>”,
“<literal>STALE</literal>”, “<literal>UPDATING</literal>”,
“<literal>REVALIDATED</literal>” или “<literal>HIT</literal>”.
</tag-desc>

<tag-name id="var_upstream_cookie_"><var>$upstream_cookie_</var><value>имя</value></tag-name>
<tag-desc>
кука с указанным <value>именем</value>, переданная сервером группы
в поле <header>Set-Cookie</header> заголовка ответа (1.7.1).
Необходимо иметь в виду, что запоминаются поля заголовка только из ответа
последнего сервера.
</tag-desc>

<tag-name id="var_upstream_response_length"><var>$upstream_response_length</var>
</tag-name>
<tag-desc>
хранит длины ответов, полученных от серверов группы (0.7.27);
длины хранятся в байтах.
Длины нескольких ответов разделяются запятыми и двоеточиями
подобно адресам в переменной <var>$upstream_addr</var>.
</tag-desc>

<tag-name id="var_upstream_response_time"><var>$upstream_response_time</var>
</tag-name>
<tag-desc>
хранит времена ответов, полученных от серверов группы;
времена хранятся в секундах с точностью до миллисекунд.
Времена нескольких ответов разделяются запятыми и двоеточиями
подобно адресам в переменной <var>$upstream_addr</var>.
</tag-desc>

<tag-name id="var_upstream_status"><var>$upstream_status</var></tag-name>
<tag-desc>
хранит коды ответов, полученных от серверов группы.
Коды нескольких ответов разделяются запятыми и двоеточиями
подобно адресам в переменной <var>$upstream_addr</var>.
</tag-desc>

<tag-name id="var_upstream_http_"><var>$upstream_http_</var><value>имя</value></tag-name>
<tag-desc>
хранят поля заголовка ответа сервера.
Например, поле заголовка ответа <header>Server</header>
доступно в переменной <var>$upstream_http_server</var>.
Правила преобразования имён полей заголовка ответа в имена переменных
такие же, как для переменных с префиксом
“<link doc="ngx_http_core_module.xml" id="variables">$http_</link>”.
Необходимо иметь в виду, что запоминаются поля заголовка только из ответа
последнего сервера.
</tag-desc>

</list>
</para>

</section>

</module>