<!-- review: finished -->

<a id="http-upstream"></a>

# Upstream

Предоставляет контекст для описания группы серверов, которые могут использоваться в директивах [proxy_pass](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [uwsgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass), [memcached_pass](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass) и [grpc_pass](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass).

<a id="configuration-example-45"></a>

## Пример конфигурации

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server backend3.example.com       service=_example._tcp resolve;
    server unix:/tmp/backend3;

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

resolver 127.0.0.53 status_zone=resolver;

server {
    location / {
        proxy_pass http://backend;
    }
}
```

<a id="directives-48"></a>

## Директивы

<a id="index-0"></a>

<a id="u-backup-switch"></a>

### backup_switch (PRO)

#### Versionadded
Добавлено в версии 1.9.0: PRO

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `backup_switch` `permanent`[=время];   |
|------------------------------------------------------------------------------------------|----------------------------------------|
| По умолчанию                                                                             | —                                      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                               |

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

Если параметр `permanent` определен без значения [времени](https://angie.software//angie/docs/configuration/configfile.md#syntax),
группа остается активной после выбора,
и автоматическая перепроверка групп с меньшим уровнем не происходит.
Если время задано,
то активный статус группы истекает через указанный интервал,
и балансировщик снова проверяет группы с меньшим уровнем,
возвращаясь к ним, если серверы работают нормально.

Пример:

```nginx
upstream my_backend {
    server primary1.example.com;
    server primary2.example.com;

    server backup1.example.com backup;
    server backup2.example.com backup;

    backup_switch permanent=2m;
}
```

Если балансировщик переключается с основных серверов на резервную группу,
все последующие запросы обрабатываются этой резервной группой в течение 2 минут.
По истечении 2 минут балансировщик повторно проверяет основные серверы
и снова делает их активными, если они работают нормально.

<a id="index-1"></a>

<a id="u-bind-conn"></a>

### bind_conn (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `bind_conn` значение;   |
|------------------------------------------------------------------------------------------|-------------------------|
| По умолчанию                                                                             | —                       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                |

Позволяет привязать серверное соединение к клиентскому в момент, когда
значение, заданное строкой из переменных, становится отличным от `""` и
`"0"`.

#### WARNING
Директива `bind_conn` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Если она используется наряду с директивой [sticky](#u-sticky),
то `bind_conn` должна стоять после `sticky`.

#### WARNING
При использовании директивы настройки модуля [Proxy](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy)
должны допускать использование постоянных соединений, например:

```nginx
proxy_http_version 1.1;
proxy_set_header Connection "";
```

Типичный пример использования директивы — проксирование соединений с
NTLM-аутентификацией, где требуется обеспечить привязку клиента к серверу в
начале согласования:

```nginx
map $http_authorization   $ntlm {
    ~*^N(?:TLM|egotiate)  1;
}

upstream ntlm_backend {
    server 127.0.0.1:8080;
    bind_conn $ntlm;
}

server {
    # ...
    location / {
        proxy_pass http://ntlm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        # ...
    }
}
```

<a id="index-2"></a>

<a id="u-feedback"></a>

### feedback (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `feedback` переменная [`inverse`] [`factor=`число] [`account=`условная_переменная] [`last_byte`];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                                   |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                                                                                            |

Задает в `upstream` механизм балансировки нагрузки по обратной связи.
Он динамически корректирует решения при балансировке,
умножая вес каждого проксируемого сервера на среднее значение обратной связи,
которое меняется с течением времени в зависимости от значения переменной
и подчиняется необязательному условию.

Могут быть заданы следующие параметры:

| `переменная`   | Переменная, из которой берется значение обратной связи.<br/>Она должна представлять собой метрику производительности или состояния;<br/>предполагается, что сервер передает ее в заголовках или иным образом.<br/><br/>Значение оценивается при каждом ответе от сервера<br/>и учитывается в скользящем среднем<br/>согласно настройкам `inverse` и `factor`.                                                                                                                                                                                                                                                                                                                                             |
|----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse`      | Если параметр задан, значение обратной связи интерпретируется наоборот:<br/>более низкие значения указывают на лучшую производительность.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `factor`       | Коэффициент, по которому значение обратной связи учитывается<br/>при расчете среднего.<br/>Допустимы целые числа от 0 до 99.<br/>По умолчанию — `90`.<br/><br/>Среднее рассчитывается по формуле [экспоненциального сглаживания](https://ru.wikipedia.org/wiki/Экспоненциальное_сглаживание).<br/><br/>Чем больше коэффициент, тем меньше новые значения влияют на среднее;<br/>если указать `90`, то будет взято 90 % от предыдущего значения<br/>и лишь 10 % от нового.                                                                                                                                                                                                                                 |
| `account`      | Указывает условную переменную,<br/>которая контролирует, какие ответы учитываются при расчете.<br/>Среднее значение обновляется с учетом значения обратной связи из ответа,<br/>только если условная переменная этого ответа<br/>не равна `""` или `"0"`.<br/><br/>#### NOTE<br/>По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)<br/>не включаются в расчет;<br/>комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>с `account` позволяет включить эти ответы<br/>или даже исключить все остальное. |
| `last_byte`    | Позволяет обрабатывать данные от проксируемого сервера после получения<br/>полного ответа, а не только заголовка.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

Пример:

```nginx
upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_http_custom_score $feedback_value {
    "high"                      100;
    "medium"                    75;
    "low"                       50;
    default                     10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}
```

Эта конфигурация категоризирует ответы серверов по уровням обратной связи
на основе определенных оценок из полей заголовков ответа,
а также добавляет условие на [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe),
чтобы учитывать только ответы от активной проверки `high_priority`
или ответы на обычные клиентские запросы.

<a id="index-3"></a>

<a id="u-hash"></a>

### hash

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `hash` ключ [`consistent`];   |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию                                                                             | —                             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                      |

Задает метод балансировки нагрузки для группы, при котором соответствие клиента
серверу определяется при помощи хэшированного значения ключа. В качестве ключа
может использоваться текст, переменные и их комбинации. Следует отметить, что
любое добавление или удаление серверов в группе может привести к
перераспределению большинства ключей на другие серверы. Метод совместим с
библиотекой Perl [Cache::Memcached](https://metacpan.org/pod/Cache::Memcached).

```nginx
hash $remote_addr;
```

При использовании доменных имен, разрешающихся в несколько IP-адресов
(например, с параметром `resolve`),
сервер не сортирует полученные адреса, поэтому их порядок может различаться
на разных серверах, что влияет на распределение клиентов.
Чтобы обеспечить одинаковое распределение,
используйте параметр `consistent`.

Если задан параметр `consistent`, то вместо вышеописанного метода будет
использоваться метод консистентного хэширования [ketama](https://www.metabrew.com/article/libketama-consistent-hashing-algo-memcached-clients).
Метод гарантирует, что при добавлении сервера в группу или его удалении на
другие серверы будет перераспределено минимальное число ключей. Применение
метода для кэширующих серверов обеспечивает больший процент попаданий в кэш.
Метод совместим с библиотекой Perl [Cache::Memcached::Fast](https://metacpan.org/pod/Cache::Memcached::Fast) при значении параметра
`ketama_points`, равном 160.

<a id="index-4"></a>

<a id="u-ip-hash"></a>

### ip_hash

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `ip_hash`;   |
|------------------------------------------------------------------------------------------|--------------|
| По умолчанию                                                                             | —            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream     |

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

Если один из серверов нужно убрать на некоторое время, то для сохранения текущего хэширования IP-адресов клиентов этот сервер нужно пометить параметром `down`:

```nginx
upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}
```

<a id="index-5"></a>

<a id="u-keepalive"></a>

### keepalive

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive` соединения;   |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию                                                                             | —                         |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                  |

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

Параметр `соединения` устанавливает максимальное число неактивных
постоянных соединений с серверами группы, которые будут сохраняться в кэше
каждого рабочего процесса. При превышении этого числа наиболее давно не
используемые соединения закрываются.

#### NOTE
Следует особо отметить, что директива keepalive не ограничивает общее число соединений с серверами группы, которые рабочие процессы Angie могут открыть. Параметр соединения следует устанавливать достаточно консервативно, чтобы серверы группы по-прежнему могли обрабатывать новые входящие соединения.

#### WARNING
Директива `keepalive` должна использоваться после всех директив, задающих
тот или иной метод балансировки нагрузки, иначе она не будет работать.

Пример конфигурации группы серверов memcached с постоянными соединениями:

```nginx
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;
    }

}
```

Для HTTP директиву [proxy_http_version](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) следует установить в "1.1", а поле заголовка `Connection` — очистить:

```nginx
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 "";
    #    ...
    }
}
```

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

Для работы постоянных соединений с FastCGI-серверами потребуется включить директиву [fastcgi_keep_conn](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-keep-conn):

```nginx
upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    #...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
    #    ...
    }
}
```

#### NOTE
Протоколы SCGI и uwsgi не определяют семантику постоянных соединений.

<a id="index-6"></a>

<a id="u-keepalive-requests"></a>

### keepalive_requests

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_requests` число;   |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию                                                                             | `keepalive_requests 1000;`    |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                      |

Задает максимальное число запросов, которые можно сделать по одному постоянному соединению. После того как сделано максимальное число запросов, соединение закрывается.

Периодическое закрытие соединений необходимо для освобождения памяти, выделенной под конкретные соединения. Поэтому использование слишком большого максимального числа запросов может приводить к чрезмерному потреблению памяти и не рекомендуется.

<a id="index-7"></a>

<a id="u-keepalive-time"></a>

### keepalive_time

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_time` время;   |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию                                                                             | `keepalive_time 1h;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                  |

Ограничивает максимальное время, в течение которого могут обрабатываться запросы в рамках постоянного соединения. По достижении заданного времени соединение закрывается после обработки очередного запроса.

<a id="index-8"></a>

<a id="u-keepalive-timeout"></a>

### keepalive_timeout

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_timeout` время;   |
|------------------------------------------------------------------------------------------|------------------------------|
| По умолчанию                                                                             | `keepalive_timeout 60s;`     |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                     |

Задает таймаут, в течение которого неактивное постоянное соединение с сервером группы не будет закрыто.

<a id="index-9"></a>

<a id="u-least-conn"></a>

### least_conn

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_conn`;   |
|------------------------------------------------------------------------------------------|-----------------|
| По умолчанию                                                                             | —               |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream        |

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

<a id="index-10"></a>

<a id="u-least-time"></a>

### least_time (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_time` `header` | `last_byte` [`factor=`число] [`account=`условная_переменная];   |
|------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                       |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                                                                                |

Задает для группы метод балансировки нагрузки, при котором вероятность передачи
запроса активному серверу обратно пропорциональна среднему времени его ответа;
чем оно меньше, тем больше запросов будет получать сервер.

| `header`    | Директива учитывает среднее время получения заголовков ответа.   |
|-------------|------------------------------------------------------------------|
| `last_byte` | Директива использует среднее время получения полного ответа.     |

| `factor`   | Выполняет ту же функцию, что и [response_time_factor (PRO)](#u-response-time-factor),<br/>и переопределяет его, если параметр задан.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account`  | Указывает условную переменную,<br/>которая контролирует, какие ответы учитываются при расчете.<br/>Среднее значение обновляется,<br/>только если условная переменная ответа<br/>не равна `""` или `"0"`.<br/><br/>#### NOTE<br/>По умолчанию ответы в ходе [активных проверок](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)<br/>не включаются в расчет;<br/>комбинация переменной [$upstream_probe](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>с `account` позволяет включить эти ответы<br/>или даже исключить все остальное. |

Текущие значения представлены как `header_time` (только заголовки)
и `response_time` (ответы целиком) в объекте `health` сервера
среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) в API.

<a id="index-11"></a>

<a id="u-queue"></a>

### queue (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `queue` число [`timeout=`время];   |
|------------------------------------------------------------------------------------------|------------------------------------|
| По умолчанию                                                                             | —                                  |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                           |

Если для запроса не удается назначить проксируемый сервер с первой попытки
(например, при краткосрочном перебое в работе
или всплеске нагрузки с достижением предела [max_conns](#u-server)),
запрос не отклоняется;
вместо этого Angie пытается поставить его в очередь на обработку.

Численный параметр директивы задает максимальное количество запросов
в очереди [рабочего процесса](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes).
Если очередь целиком заполнена,
клиенту отдается ошибка `502 (Bad Gateway)`.

#### NOTE
К запросам в очереди также применяется логика директивы
[proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream).
В частности, если для запроса был выбран сервер,
но передать его туда не удалось,
то он может вернуться в очередь.

Если сервер для передачи запроса в очереди не был выбран
за [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) `timeout`
(по умолчанию — 60 секунд),
клиенту отдается ошибка `502 (Bad Gateway)`.
Еще из очереди удаляются запросы от клиентов,
преждевременно закрывших соединение;
в [API](https://angie.software//angie/docs/configuration/modules/http/http_api.md#a-queue) есть счетчики состояний запросов,
проходящих через очередь.

#### WARNING
Директива `queue` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки, иначе она не будет
работать.

<a id="index-12"></a>

<a id="u-random"></a>

### random

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `random` [`two`];   |
|------------------------------------------------------------------------------------------|---------------------|
| По умолчанию                                                                             | —                   |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream            |

Задает для группы метод балансировки нагрузки, при котором запрос передается случайно выбранному серверу, с учетом весов серверов.

Если указан необязательный параметр `two`, Angie случайным образом выбирает два сервера, из которых выбирает сервер, используя метод [least_conn](#u-least-conn), при котором запрос передается на сервер с наименьшим количеством активных соединений.

<a id="index-13"></a>

<a id="u-response-time-factor"></a>

### response_time_factor (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `response_time_factor` число;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию                                                                             | `response_time_factor 90;`      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                        |

Задает для метода балансировки нагрузки [least_time (PRO)](#u-least-time) коэффициент
сглаживания **предыдущего** значения при вычислении среднего времени ответа по формуле
[экспоненциально взвешенного скользящего среднего](https://ru.wikipedia.org/wiki/Скользящая_средняя#Экспоненциально_взвешенное_скользящее_среднее).

Чем больше указанное число, тем меньше новые значения влияют на среднее; если
указать `90`, то будет взято 90 % от предыдущего значения и лишь 10 % от
нового. Допустимые значения — от 0 до 99 включительно.

Текущие результаты вычислений представлены как `header_time`
(только заголовки) и `response_time` (ответы целиком) в объекте `health`
сервера среди [метрик апстрима](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) в API.

#### NOTE
При подсчете учитываются только успешные ответы; что считать неуспешным
ответом, определяют директивы [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream) и
[grpc_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream). Кроме того, значение `header_time`
пересчитывается, только если получены и обработаны все заголовки, а
`response_time` — только если получен весь ответ.

<a id="index-14"></a>

<a id="u-server"></a>

### server

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` адрес [параметры];   |
|------------------------------------------------------------------------------------------|-------------------------------|
| По умолчанию                                                                             | —                             |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                      |

Задает адрес и другие параметры сервера. Адрес может быть указан в виде доменного имени или IP-адреса, и необязательного порта, или в виде пути UNIX-сокета, который указывается после префикса `unix:`. Если порт не указан, используется порт 80. Доменное имя, которому соответствует несколько IP-адресов, задает сразу несколько серверов.

Могут быть заданы следующие параметры:

| `weight=`число    | Задает вес сервера. По умолчанию — 1.                                                                                                                                                                                                                                                      |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`число | Ограничивает максимальное число одновременных активных соединений к проксируемому серверу. Значение по умолчанию равно `0` и означает, что ограничения нет. Если группа не находится в [зоне разделяемой памяти](#u-zone), то ограничение работает отдельно для каждого рабочего процесса. |

#### NOTE
При включенных [неактивных постоянных соединениях](#u-keepalive), нескольких [рабочих процессах](https://angie.software//angie/docs/configuration/modules/core.md#worker-processes) и [зоне разделяемой памяти](#u-zone) суммарное число активных и неактивных соединений с проксируемым сервером может превышать значение `max_conns`.

<a id="max-fails"></a>

`max_fails=`число — задает число неудачных попыток связи с сервером,
которые должны произойти в течение заданного [fail_timeout](#fail-timeout)
времени для того, чтобы сервер считался недоступным;
после этого он будет повторно проверен через то же самое время.

Что считается неудачной попыткой,
определяется директивами [proxy_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream) и
[grpc_next_upstream](https://angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream).

При превышении `max_fails` сервер также признается неработающим с точки зрения
[upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe); клиентские запросы не будут направляться к нему,
пока проверки не признают его работающим.

#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `max_fails` применяется к каждому серверу отдельно.

Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `max_fails` не действует и будет проигнорирована.

| `max_fails=1`   | Число попыток по умолчанию;   |
|-----------------|-------------------------------|
| `max_fails=0`   | Отключает учет попыток.       |

<a id="fail-timeout"></a>

`fail_timeout=`время — задает период времени, в течение которого
должно произойти определенное число неудачных попыток связи с сервером
([max_fails](#max-fails)), чтобы сервер считался недоступным.
Затем сервер остается недоступным в течение того же самого времени,
прежде чем будет проверен повторно.

Значение по умолчанию — 10 секунд.

#### NOTE
Если директива `server` в группе разрешается в несколько серверов,
ее настройка `fail_timeout` применяется к каждому серверу отдельно.

Если после разрешения всех директив `server`
в апстриме остается только один сервер,
настройка `fail_timeout` не действует и будет проигнорирована.

| `backup`      | Помечает сервер как запасной. На него будут передаваться запросы в случае, если не работают основные серверы.<br/><br/>Если задана директива [backup_switch (PRO)](#u-backup-switch),<br/>также применяется ее логика активного резервирования.   |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down`        | Помечает сервер как постоянно недоступный.                                                                                                                                                                                                        |
| `drain` (PRO) | Помечает сервер как разгружаемый (draining); это значит,<br/>что он получает только запросы сессий,<br/>привязанных ранее через [sticky](#u-sticky).<br/>В остальном поведение такое же, как в режиме `down`.                                     |

#### WARNING
Параметр `backup` нельзя использовать совместно с методами
балансировки нагрузки [hash](#u-hash), [ip_hash](#u-ip-hash) и
[random](#u-random).

Параметры `down` и `drain` взаимно исключающие.

<a id="reresolve"></a>

| `resolve`     | Позволяет отслеживать изменения списка IP-адресов, соответствующего<br/>доменному имени, и обновлять его без перезагрузки конфигурации.<br/>При этом группа должна находиться в<br/>[зоне разделяемой памяти](#u-zone);<br/>также должен быть определен<br/>[преобразователь имен в адреса](https://angie.software//angie/docs/configuration/modules/http/index.md#resolver).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
|---------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`имя | Включает преобразование SRV-записей DNS и задает имя сервиса. Для<br/>работы параметра необходимо задать параметр `resolve` у сервера,<br/>не указывая порт сервера при имени хоста.<br/><br/>Если в имени службы нет точек, формируется имя по стандарту RFC:<br/>к имени службы добавляется префикс `_`,<br/>затем через точку добавляется `_tcp`.<br/>Так, имя службы `http` даст в результате `_http._tcp`.<br/><br/>Angie разрешает SRV-записи,<br/>объединяя нормализованное имя службы и имя хоста<br/>и получая список серверов для полученной комбинации через DNS,<br/>вместе с их приоритетами и весами.<br/><br/>- SRV-записи с наивысшим приоритетом<br/>  (те, которые имеют минимальное значение приоритета)<br/>  разрешаются как основные серверы,<br/>  а прочие записи становятся запасными серверами.<br/>  Если `backup` установлено с `server`,<br/>  SRV-записи с наивысшим приоритетом разрешаются как запасные серверы,<br/>  а прочие записи игнорируются.<br/>- Вес аналогичен параметру `weight` директивы `server`.<br/>  Если вес задан как в самой директиве, так и в SRV-записи,<br/>  используется вес, установленный в директиве. |

В этом примере выполняется поиск записи `_http._tcp.backend.example.com`:

```nginx
server backend.example.com service=http resolve;
```

| `sid=`id   | Задает ID сервера в группе. Если параметр не задан,<br/>то ID задается как шестнадцатеричный MD5-хэш<br/>IP-адреса и порта или пути UNIX-сокета.   |
|------------|----------------------------------------------------------------------------------------------------------------------------------------------------|

<a id="slow-start"></a>

| `slow_start=`время   | Задает [время](https://angie.software//angie/docs/configuration/configfile.md#syntax) восстановления веса сервера,<br/>возвращающегося к работе<br/>при балансировке нагрузки методом<br/>[round-robin](#round-robin) или [least_conn](#u-least-conn).<br/><br/>Если параметр задан<br/>и сервер после сбоя снова считается работающим<br/>с точки зрения [max_fails](#max-fails) и [upstream_probe (PRO)](https://angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),<br/>то такой сервер равномерно набирает указанный для него вес<br/>в течение заданного времени.<br/><br/>Если параметр не задан,<br/>то в аналогичной ситуации<br/>сервер сразу начинает работу с указанным для него весом.   |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### NOTE
Если в апстриме задан только один `server`,
`slow_start` не работает и будет игнорироваться.

<a id="index-15"></a>

<a id="u-state"></a>

### state (PRO)

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `state` файл;   |
|------------------------------------------------------------------------------------------|-----------------|
| По умолчанию                                                                             | —               |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream        |

Указывает файл, где постоянно хранится список серверов апстрима.
При установке из
[наших пакетов](https://angie.software//angie/docs/installation/index.md#install-packages)
для хранения таких файлов специально создается каталог
`/var/lib/angie/state/` (`/var/db/angie/state/` во FreeBSD)
с соответствующими правами доступа,
и в конфигурации остается добавить лишь имя файла:

```nginx
upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<ИМЯ ФАЙЛА>;
}
```

Список серверов здесь имеет формат, аналогичный `server`.
Содержимое файла изменяется при любом изменении серверов в разделе
[/config/http/upstreams/](https://angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-http-upstreams-servers)
через API конфигурации.
Файл считывается при запуске Angie или перезагрузке конфигурации.

#### WARNING
Чтобы использовать директиву `state` в блоке `upstream`,
в нем не должно быть директив `server`,
но нужна зона разделяемой памяти ([zone](#u-zone)).

<a id="index-16"></a>

<a id="u-sticky"></a>

### sticky

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky` cookie name [attr=значение]...;<br/><br/>`sticky route` значение...;<br/><br/>`sticky learn` `zone=`зона `create=`$create_var1... `lookup=`$lookup_var1... [`header`] [`norefresh`] [`timeout=`время];<br/><br/>`sticky learn` [`zone=`зона] `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`norefresh`] [`timeout=`время];   |
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| По умолчанию                                                                             | —                                                                                                                                                                                                                                                                                                                                                                 |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                                                                                                                                                                                                                                                                                                                                                          |

Настраивает привязку клиентских сессий к проксируемым серверам
в режиме, заданном первым параметром;
для разгрузки серверов,
у которых задана директива `sticky`,
можно использовать опцию `drain` (PRO)
в блоке [server](#u-server).

#### WARNING
Директива `sticky` должна использоваться после всех директив,
задающих тот или иной метод балансировки нагрузки,
иначе она не будет работать.
Если она используется наряду с директивой [bind_conn (PRO)](#u-bind-conn),
то `bind_conn` должна стоять после `sticky`.

Режим `cookie`

Этот режим использует cookie для хранения сессий.
Он подходит для ситуаций,
когда cookie уже используются для управления сессиями.

Здесь запрос от клиента,
пока не привязанного к какому-то серверу,
отправляется на сервер,
выбираемый согласно настроенному методу балансировки.
При этом Angie устанавливает cookie
с уникальным значением, идентифицирующим сервер.

Имя cookie (`name`) задается директивой `sticky`,
а значение (`value`) соответствует
параметру [sid](#reresolve)
директивы [server](#u-server).
Учтите, что параметр дополнительно хэшируется,
если задана директива [sticky_secret](#u-sticky-secret).

Последующие запросы от клиента, содержащие такой cookie,
передаются на сервер, заданный значением cookie,
то есть сервер с указанным [sid](#reresolve).
Если выбрать сервер не удается
или выбранный сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.

Директива позволяет назначать атрибуты такого cookie;
единственный атрибут, устанавливаемый по умолчанию, — `path=/`.
Значения атрибутов задаются строками с переменными.
Чтобы удалить атрибут, задайте для него пустое значение: `attr=`.
Так, `sticky cookie path=` задает cookie без атрибута `path`.

Здесь Angie создает cookie `srv_id` со сроком действия в 1 час
и доменом, заданным переменной:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie srv_id domain=$my_domain max-age=3600;
}
```

Режим `route`

Этот режим использует предопределенные идентификаторы маршрутов,
которые могут быть встроены в URL, cookie или другие свойства запроса.
Он менее гибок, так как зависит от предопределенных значений,
но лучше подходит, если такие идентификаторы уже используются.

Здесь проксируемый сервер при получении запроса
может назначить клиенту маршрут и вернуть его идентификатор способом,
известным им обоим.
В качестве идентификатора маршрута
должно использоваться значение параметра [sid](#reresolve)
директивы [server](#u-server).
Учтите, что параметр дополнительно хэшируется,
если задана директива [sticky_secret](#u-sticky-secret).

Последующие запросы от клиентов, желающих использовать этот маршрут,
должны содержать выданный сервером идентификатор, причем так,
чтобы он попал в переменные Angie, например
в [cookie](https://angie.software//angie/docs/configuration/modules/http/index.md#v-cookie) или [аргументы запроса](https://angie.software//angie/docs/configuration/modules/http/index.md#v-arg).

В параметрах директивы указываются строки, которые могут содержать
переменные, чтобы извлечь идентификатор маршрута.
Чтобы выбрать сервер, куда передается поступивший запрос,
используется первое непустое значение;
она затем сравнивается с параметром [sid](#reresolve)
директивы [server](#u-server).
Если выбрать сервер не удается
или выбранный сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.

Здесь Angie ищет идентификатор маршрута в cookie `route`,
затем в аргументе запроса `route`:

```nginx
upstream backend {
    server backend1.example.com:8080 "sid=server 1";
    server backend2.example.com:8080 "sid=server 2";

    sticky route $cookie_route $arg_route;
}
```

Режим `learn` (PRO 1.4.0+)

В этом режиме для привязки клиента к конкретному проксируемому серверу
используется динамически генерируемый ключ;
этот режим более гибок,
так как назначает серверы на ходу,
хранит сеансы в зоне разделяемой памяти
и поддерживает различные способы передачи идентификаторов сессий.

Здесь сессия создается
на основе ответа проксируемого сервера.
С параметрами `create` и `lookup` перечисляются переменные,
указывающие, как создаются новые и ищутся существующие сессии.
Оба параметра можно использовать по нескольку раз.

Идентификатором сессии служит значение первой непустой переменной,
указанной с `create`;
например, это может быть
[cookie с проксируемого сервера](#v-upstream-cookie).

Сессии хранятся в зоне разделяемой памяти;
ее имя и размер задаются параметром `zone`.
Если к сессии не было обращений в течение [времени](https://angie.software//angie/docs/configuration/configfile.md#syntax)
`timeout`, она удаляется.
Значение по умолчанию — 1 час.

По умолчанию Angie продлевает срок действия сессии,
обновляя метку времени последнего обращения при каждом использовании.
Параметр `norefresh` отключает это поведение:
сессия истечет строго по таймауту, даже если продолжает использоваться.
Такой режим удобен,
когда требуется принудительно завершать сессию по истечении времени,
например, при интеграции с внешними менеджерами сессий.

Последующие запросы от клиентов, желающих использовать сессию,
должны содержать ее идентификатор.
Параметр `lookup` ищет идентификатор сессии в пользовательском запросе
по заданному для него списку переменных,
останавливаясь на первой непустой.
Если ничего не найдено — запрос считается новым.
Значение найденного идентификатора
сопоставляется с сессиями в разделяемой памяти.
Если выбрать сервер не удается
или выбранный сервер не может обработать запрос,
то будет выбран другой сервер
согласно настроенному методу балансировки.

Параметр `header` позволяет создать сессию
сразу после получения заголовков ответа от проксируемого сервера.
Без него сессия создается только после завершения обработки запроса.

В примере Angie создает сессию,
устанавливая в ответе cookie с именем `examplecookie`:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky learn
        create=$upstream_cookie_examplecookie
        lookup=$cookie_examplecookie
        zone=client_sessions:1m;
}
```

Режим `learn` с `remote_action` (PRO 1.8.0+)

Параметры `remote_action` и `remote_result`
позволяют динамически назначать идентификаторы сессий и управлять ими
с использованием удаленного хранилища сессий.
При этом зона разделяемой памяти выступает в роли локального кэша,
а удаленное хранилище является авторитетным источником.
Поэтому параметр `create`
несовместим с `remote_action`,
так как идентификаторы сессий должны создаваться удаленно.

Если к сессии не было обращений в течение [времени](https://angie.software//angie/docs/configuration/configfile.md#syntax)
`timeout`, она удаляется.
Значение по умолчанию — 1 час.
Настройка `remote_action` не влияет на таймаут.

По умолчанию Angie продлевает срок действия сессии,
обновляя метку времени последнего обращения при каждом ее использовании.
Параметр `norefresh` меняет это поведение:
сессия истекает строго по таймауту, даже если используется.

Параметр `zone`
в конфигурации `sticky` с `remote_action`
необязателен.
Если он не задан,
Angie полностью полагается на удаленное хранилище:
не кэширует сессии локально
(хотя позволяет кэшировать ответы хранилища через `proxy_cache`)
и обращается к удаленному хранилищу всякий раз,
когда требуется получить или создать сессию.

Общий принцип работы режима таков:
если идентификатор сессии не найден локально или истек таймаут,
Angie отправляет синхронный подзапрос в некое удаленное хранилище,
заданное параметром `remote_action`.

При поступлении HTTP-запроса Angie выполняет следующие действия:

- Сначала извлекается идентификатор сессии из первой непустой переменной
  в списке `lookup`.
  Если все переменные пустые,
  используется обычный алгоритм балансировки нагрузки без привязки.
- Если задан параметр `zone`,
  Angie ищет существующую сессию в локальной разделяемой памяти.
  При обнаружении используется связанный с ней сервер
  и обработка завершается.
- Если сессия не найдена локально или параметр `zone` не задан,
  сервер выбирается как обычно, согласно настроенному методу балансировки.
  Затем Angie отправляет в удаленное хранилище,
  заданное параметром `remote_action`, синхронный HTTP-подзапрос,
  который должен содержать в понятном хранилищу виде:
  - идентификатор  *сессии* из параметра `lookup`
    (в конфигурации это переменная
    [$sticky_sessid](#v-sticky-sessid));
  - идентификатор предварительно выбранного  *сервера*:
    значение параметра `sid=` из директивы `server`,
    если оно задано,
    либо MD5-хэш имени сервера
    (в конфигурации это переменная
    [$sticky_sid](#v-sticky-sid)).

  Проще всего можно передать эти идентификаторы через HTTP-заголовки
  с помощью [proxy_set_header](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header).
- Удаленное хранилище обрабатывает запрос и возвращает HTTP-ответ:

  Ответ с кодом 200, 201 или 204 подтверждает выбранный сервер.
  Если задан параметр `zone`,
  сессия сохраняется в зоне разделяемой памяти.

  Ответ с кодом 409 указывает на конфликт (лишь при наличии `zone`):
  данный идентификатор сессии уже существует, но связан с другим сервером.
  Удаленное хранилище должно одновременно с этим
  вернуть правильный идентификатор сервера в HTTP-заголовке;
  извлечь его можно через `remote_result`.

  При получении от хранилища любого другого HTTP-кода
  (включая ошибки сети и таймауты)
  либо несуществующего идентификатора сервера
  Angie использует изначально выбранный сервер.

Идентификатор сервера извлекается из ответа удаленного хранилища
через параметр `remote_result`:
в нем можно указывать переменные
с префиксом `upstream_http_`,
которые создаются Angie автоматически для доступа
к заголовкам HTTP-ответов от удаленного хранилища.
Например, заголовок `X-Sid: server1` в таком ответе
становится доступным в переменной `$upstream_http_x_sid`
со значением `server1`.

В следующем примере Angie создает сессию,
использует переменную `$cookie_bar`
для начального идентификатора сессии,
а альтернативные идентификаторы сессий, возвращенные удаленным хранилищем,
сохраняет в `$upstream_http_x_sticky_sid`:

```nginx
http {

    upstream u1 {

        server srv1;
        server srv2;

        sticky learn zone=sz:1m
            lookup=$cookie_bar
            remote_action=/remote_session
            remote_result=$upstream_http_x_sticky_sid;

        zone z 1m;
    }

    server {

        listen localhost;

        location / {

            proxy_pass http://u1/;
        }

        location /remote_session {

            internal;
            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid $sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://remote;
        }
    }
}
```

Ниже показан упрощенный пример конфигурации.
Удаленное хранилище возвращает идентификатор сессии в заголовке `X-Sid`
и таким образом подтверждает или переопределяет выбор Angie:

```nginx
http {

    proxy_cache_path c1 keys_zone=s1:1m;

    upstream tc_0 {
        server 10.0.0.1 sid=web-server-01;
        server 10.0.0.2 sid=web-server-02;

        sticky learn
            lookup=$arg_id
            remote_action=@create_session
            remote_result=$upstream_http_x_sid;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            proxy_pass http://tc_0/;
        }

        # Запрос к удаленному хранилищу сессий
        location @create_session {
            internal;

            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid    $sticky_sid;
            proxy_set_header X-Sticky-Last   $msec;

            proxy_pass http://session_backend;

            proxy_connect_timeout 1s;
            proxy_read_timeout    1s;

            proxy_cache        s1;
            proxy_cache_valid  200 1d;
            proxy_cache_key    "$scheme$proxy_host$request_uri$sticky_sessid";
        }
    }
}
```

Здесь при следующем ответе от удаленного хранилища:

```none
HTTP/1.1 200 OK
...
X-Sid: web-server-01
X-Session-Backend: backend-pool-1
```

Становятся доступными две переменные:

- `$upstream_http_x_sid`,
  со значением `web-server-01`;
- `$upstream_http_x_session_backend`,
  со значением  `backend-pool-1`.

Так как переменная `$upstream_http_x_sid`
указана в параметре `remote_result`,
то ее значение будет использовано
для выбора сервера с `sid=web-server-01`.

Директива `sticky` учитывает состояние серверов в [upstream](#u-upstream):

- Cерверы, помеченные как `down` или временно недоступные из-за сбоев,
  исключаются из выбора.
- Cерверы, которые достигли максимального количества соединений
  (при использовании `max_conns`), временно пропускаются.
- Cерверы с опцией `drain` (PRO)
  могут быть выбраны для создания новых сессий в режиме `sticky`
  при совпадении идентификаторов.
- Если ранее недоступный сервер восстанавливается,
  `sticky` автоматически возобновляет его использование.

Поведение `sticky` можно дополнительно настроить
директивами [sticky_secret](#u-sticky-secret) и [sticky_strict](#u-sticky-strict).
Если в ходе работы `sticky` выбрать сервер не удается или он недоступен,
запрос будет обработан согласно выбранному методу балансировки нагрузки,
если только не включена директива `sticky_strict`.
В режиме `sticky_strict on;` запрос отклоняется с ошибкой.

Зоны разделяемой памяти,
указываемые в параметре `zone` директивы `sticky`,
не могут использоваться совместно различными `upstream`;
каждая группа должна использовать свою собственную зону.

<a id="index-17"></a>

<a id="u-sticky-secret"></a>

### sticky_secret

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_secret` строка;   |
|------------------------------------------------------------------------------------------|---------------------------|
| По умолчанию                                                                             | —                         |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                  |

Добавляет строку как соль в функцию MD5-хэширования
для директивы [sticky](#u-sticky) в режимах `cookie` и `route`.
Строка может содержать переменные, например `$remote_addr`:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}
```

Соль добавляется после хэшируемого значения;
чтобы независимо проверить механизм хэширования:

```console
$ echo -n "<VALUE><SALT>" | md5sum
```

<a id="index-18"></a>

<a id="u-sticky-strict"></a>

### sticky_strict

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_strict` `on` | `off`;   |
|------------------------------------------------------------------------------------------|---------------------------------|
| По умолчанию                                                                             | `sticky_strict off;`            |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream                        |

При включении Angie будет возвращать клиенту ошибку HTTP 502,
если желаемый сервер недоступен,
вместо использования любого другого доступного сервера,
как это происходит, когда в группе нет доступных серверов.

<a id="index-19"></a>

<a id="u-upstream"></a>

### upstream

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream` имя { ... }   |
|------------------------------------------------------------------------------------------|--------------------------|
| По умолчанию                                                                             | —                        |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | http                     |

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

Пример:

```nginx
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;
}
```

<a id="round-robin"></a>

По умолчанию запросы распределяются по серверам циклически (в режиме round-robin) с учетом весов серверов. В вышеприведенном примере каждые 7 запросов будут распределены так: 5 запросов на backend1.example.com и по одному запросу на второй и третий серверы.

Если при попытке работы с сервером происходит ошибка, то запрос передается следующему серверу, и так далее до тех пор, пока не будут опробованы все работающие серверы. Если не удастся получить успешный ответ ни от одного из серверов, то клиенту будет возвращен результат работы с последним сервером.

<a id="index-20"></a>

<a id="u-zone"></a>

### zone

| [Синтаксис](https://angie.software//angie/docs/configuration/configfile.md#configfile)   | `zone` имя [размер];   |
|------------------------------------------------------------------------------------------|------------------------|
| По умолчанию                                                                             | —                      |
| [Контекст](https://angie.software//angie/docs/configuration/configfile.md#configfile)    | upstream               |

Задает имя и размер зоны разделяемой памяти, в которой хранятся конфигурация группы и ее рабочее состояние, разделяемые между рабочими процессами. В одной и той же зоне могут быть сразу несколько групп. В этом случае достаточно указать размер только один раз.

#### NOTE
Содержимое зоны сохраняется при перезагрузке только в том случае, если
настроенный `размер` не изменился. Любое изменение — увеличение
или уменьшение — приводит к пересозданию зоны с потерей всех данных.

<a id="built-in-variables-14"></a>

## Встроенные переменные

Модуль `http_upstream` поддерживает следующие встроенные переменные:

<a id="v-sticky-sessid"></a>

### `$sticky_sessid`

Используется с `remote_action` в [sticky](#u-sticky);
хранит начальный идентификатор сессии, взятый из `lookup`.

<a id="v-sticky-sid"></a>

### `$sticky_sid`

Используется с `remote_action` в [sticky](#u-sticky);
хранит идентификатор сервера, предварительно связанный с сессией.

<a id="v-upstream-addr"></a>

### `$upstream_addr`

хранит IP-адрес и порт или путь к UNIX-сокету сервера группы. Если при обработке запроса были сделаны обращения к нескольким серверам, то их адреса разделяются запятой, например:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock

Если произошло внутреннее перенаправление от одной группы серверов на другую с помощью `X-Accel-Redirect` или [error_page](https://angie.software//angie/docs/configuration/modules/http/index.md#error-page), то адреса, соответствующие разным группам серверов, разделяются двоеточием, например:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80

Если сервер не может быть выбран, то переменная хранит имя [группы серверов](#u-upstream).

<a id="v-upstream-bytes-received"></a>

### `$upstream_bytes_received`

число байт, полученных от сервера группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-bytes-sent"></a>

### `$upstream_bytes_sent`

число байт, переданных на сервер группы. Значения нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-cache-status"></a>

### `$upstream_cache_status`

хранит статус доступа к кэшу ответов. Статус может быть одним из `MISS`,
`BYPASS`, `EXPIRED`, `STALE`, `UPDATING`,
`REVALIDATED` или `HIT`:

- `MISS`: Ответ не найден в кэше,
  и запрос передан на сервер.
- `BYPASS`: Кэш обойден,
  и запрос напрямую передан на сервер.
- `EXPIRED`: Ответ в кэше устарел,
  и на сервер передан новый запрос для обновления контента.
- `STALE`: Ответ в кэше устарел,
  но по-прежнему передается клиентам,
  пока через какое-то время не произойдет обновление контента c сервера.
- `UPDATING`: Ответ в кэше устарел,
  но по-прежнему передается клиентам,
  пока уже идущее обновление контента c сервера не завершится.
- `REVALIDATED`: Ответ в кэше устарел,
  но был успешно перепроверен
  и не нуждается в обновлении с сервера.
- `HIT`: Ответ был взят из кэша.

Если запрос пошел в обход кэша без обращения к нему,
переменная не устанавливается.

<a id="v-upstream-cache-key"></a>

### `$upstream_cache_key`

содержит используемый ключ кэширования.

<a id="v-upstream-connect-time"></a>

### `$upstream_connect_time`

хранит время, затраченное на установление соединения с сервером группы; время хранится в секундах с точностью до миллисекунд. В случае SSL включает в себя время, потраченное на рукопожатие. Времена нескольких соединений разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-cookie"></a>

### `$upstream_cookie_<имя>`

cookie с указанным именем, переданный сервером группы в поле `Set-Cookie` заголовка ответа. Необходимо иметь в виду, что cookie запоминаются только из ответа последнего сервера.

<a id="v-upstream-header-time"></a>

### `$upstream_header_time`

хранит время, затраченное на получение заголовка ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-http"></a>

### `$upstream_http_<имя>`

хранят поля заголовка ответа сервера. Например, поле заголовка ответа `Server` доступно в переменной `$upstream_http_server`. Правила преобразования имен полей заголовка ответа в имена переменных такие же, как для переменных с префиксом `$http_`. Необходимо иметь в виду, что поля заголовка запоминаются только из ответа последнего сервера.

<a id="v-upstream-request-method"></a>

### `$upstream_request_method`

метод запроса, используемый при обращении к upstream. Он может отличаться от
метода запроса клиента, когда кэширование преобразует `HEAD` в
`GET` или задана директива [proxy_method](https://angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method).

<a id="v-upstream-queue-time"></a>

### `$upstream_queue_time`

хранит время, проведенное запросом в [очереди](#u-queue)
до очередного выбора сервера
и выраженное в секундах с точностью до миллисекунд.
Времена нескольких попыток разделяются запятыми и двоеточиями
подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-response-length"></a>

### `$upstream_response_length`

хранит длину ответа, полученного от сервера группы; длина хранится в байтах. Длины нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-response-time"></a>

### `$upstream_response_time`

хранит время, затраченное на получение ответа от сервера группы; время хранится в секундах с точностью до миллисекунд. Времена нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-status"></a>

### `$upstream_status`

хранит статус ответа, полученного от сервера группы. Статусы нескольких ответов разделяются запятыми и двоеточиями подобно адресам в переменной [$upstream_addr](#v-upstream-addr). Если сервер не может быть выбран, то переменная хранит статус 502 (Bad Gateway).

<a id="v-upstream-sticky-status"></a>

### `$upstream_sticky_status`

Статус привязанных запросов.

| `""`   | Запрос отправлен в группу серверов, где привязка не включена.                    |
|--------|----------------------------------------------------------------------------------|
| `NEW`  | Запрос не содержит информации о привязке к серверу.                              |
| `HIT`  | Запрос с привязкой отправлен на желаемый сервер.                                 |
| `MISS` | Запрос с привязкой отправлен на сервер,<br/>выбранный по алгоритму балансировки. |

Статусы из нескольких соединений разделяются запятыми и двоеточиями
подобно адресам в переменной [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-trailer"></a>

### `$upstream_trailer_<имя>`

хранит поля из конца ответа, полученного от сервера группы.